docs
/
Client Integration

Flutter tutorial

Integrate the Flutter client with sign-in, verification, session restore and a protected read, using the complete authentication sample.

By the end of this you will have a Flutter app that signs a real person in against a real AppEngine organization, handles a verification code if their organization asks for one, keeps them signed in, and reads data as them.

The snippets below explain the integration points; they are not a complete single-file application. Use the authentication example for the complete SignInScreen, connection screen and session screen. The client configuration and trust guidance was refreshed against source on13 October 2026; this does not claim a fresh live run.

For a full developer lesson with an implemented profile/list screen, business action, mobile customization and release checks, see Custom Web and Mobile Client Development.

What you need first

Flutter with Dart 3.7 or newer for the package (Dart 3.11 for the examples), and an organization with an app credential — its App ID from Configuration › User, Group › App Credentials, with the check at Monitor or Enforce. For Chrome, a simulator or an emulator, also a debug token from the same screen. No app secret goes into the app: on a real device it proves itself with Apple App Attest or Google Play Integrity, set up as described in Phone apps without a secret. These are the app's credentials, separate from the person’s sign-in.

Run the complete reference app

With authorized access to the repositories, place them beside each other:

workspace/
  appmint-client/appmint_flutter_client/
  appmint-examples/appmint_flutter_authentication_demo/
cd appmint-examples/appmint_flutter_authentication_demo
flutter pub get
flutter run -d chrome

The authentication sample takes the API origin, organization, App ID and an optional debug token in its connection screen. The other five examples read the APPMINT_* build definitions shown at the end of this page. Browser access also needs backend CORS support. Package access or a local checkout does not establish a public license or permission to redistribute an application.

The remaining steps show how to incorporate that flow in your own project. Copy the complete sign-in and verification widgets from the sample when you need their UI; the snippets refer to host-owned fields and widgets.

Step 1 — Create the project

flutter create --org io.appmint --project-name my_appmint_app my_appmint_app
cd my_appmint_app

Step 2 — Add the client

In pubspec.yaml, under dependencies:

dependencies:
  flutter:
    sdk: flutter

  appmint_flutter_client:
    git:
      url: https://github.com/JacLight/appmint-client.git
      path: appmint_flutter_client
flutter pub get

Step 3 — Connect to your organization

Start lib/main.dart with this configuration and entry point, then add your MyApp and screens. This fragment alone does not define the widgets.

import 'package:appmint_flutter_client/appmint_flutter_client.dart';
import 'package:flutter/material.dart';

/// Values come in at build time, so nothing lives in your repository.
const config = AppmintConfig(
  baseUrl: String.fromEnvironment('APPMINT_URL'),
  orgId: String.fromEnvironment('APPMINT_ORG'),
  appId: String.fromEnvironment('APPMINT_APP_ID'),
  // Simulators, emulators and web. Empty on a release build: App Attest /
  // Play Integrity instead.
  debugToken: String.fromEnvironment('APPMINT_DEBUG_TOKEN'),
  logRequests: true,
);

final appmint = Appmint(config);

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await appmint.auth.restore();
  runApp(const MyApp());
}

That is all the app authentication you will write. The client signs the app in before the first call (App Attest on iOS, Play Integrity on Android, or the debug token), renews the app token before it expires and after a 401, and stamps orgid on everything. You never touch a header.

Why the values come from `--dart-define`

Hardcoding them puts your organization's credentials in your git history, and in a public repository that is permanent. Note also that in a shipped mobile binary the values can be extracted. --dart-define is configuration, not secret protection. That is why no app secret goes into the app (an app credential carries System authority) and why the debug token stays out of release builds. Enforce the signed-in person’s access independently.

Step 4 — Sign somebody in

Here is the part that matters, and the part every hand-rolled client gets wrong.

Sign-in has three endings, not two. Success, refusal, and a verification code is needed. That third one comes back as an ordinary 200 with no token in it — treat it as success and you get an app that looks signed in, holds nothing, and throws the person out on the next call.

The client returns a sealed result, so the compiler will not let you forget:

Future<void> _signIn() async {
  setState(() { _busy = true; _error = null; });

  final result = await appmint.customers.signIn(
    _email.text.trim(),
    _password.text,
  );
  if (!mounted) return;

  switch (result) {
    case SignedIn():
      // Nothing to do — the auth stream rebuilds onto the session page.
      break;

    case NeedsVerification(:final challenge):
      setState(() => _busy = false);
      final finished = await showDialog<SignInResult>(
        context: context,
        barrierDismissible: false,
        builder: (_) => _CodeDialog(challenge: challenge),
      );
      if (!mounted) return;
      if (finished is SignInRejected) setState(() => _error = finished.message);
      return;

    case SignInRejected(:final message):
      setState(() => _error = message);
  }

  if (mounted) setState(() => _busy = false);
}

appmint.customers signs in the people you serve. For employees, managers and administrators use appmint.staff — they are different records on the server with different sign-in routes, and they are not interchangeable.

message on a refusal is the server's own wording and is safe to show. It says things like "bad password" rather than a code you have to translate.

Step 5 — Handle the verification code

A challenge carries everything needed to finish, so you never handle a token:

class _CodeDialog extends StatefulWidget {
  const _CodeDialog({required this.challenge});
  final VerificationChallenge challenge;

  @override
  State<_CodeDialog> createState() => _CodeDialogState();
}

class _CodeDialogState extends State<_CodeDialog> {
  final _code = TextEditingController();
  bool _busy = false;
  String? _error;

  @override
  void dispose() { _code.dispose(); super.dispose(); }

  Future<void> _verify() async {
    setState(() { _busy = true; _error = null; });

    final result = await widget.challenge.verify(_code.text.trim());
    if (!mounted) return;

    switch (result) {
      case SignedIn():
        Navigator.pop(context, result);
      case SignInRejected(:final message):
        // Inspect result.error?.reason; expired challenges need new sign-in.
        setState(() { _busy = false; _error = message; });
      case NeedsVerification():
        setState(() => _busy = false);
    }
  }

  @override
  Widget build(BuildContext context) {
    final challenge = widget.challenge;

    return AlertDialog(
      title: const Text('Verification required'),
      content: Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          Text(challenge.message),
          const SizedBox(height: 12),
          TextField(
            controller: _code,
            autofocus: true,
            maxLength: 6,
            keyboardType: TextInputType.number,
            textAlign: TextAlign.center,
            decoration:
                const InputDecoration(hintText: '000000', counterText: ''),
          ),
          if (_error != null)
            Text(_error!, style: const TextStyle(color: Colors.red)),
          if (challenge.method.canResend)
            TextButton(
              onPressed: _busy ? null : () async {
                final sent = await challenge.resend();
                if (!mounted) return;
                setState(() => _error = sent ? null : 'Could not send code.');
              },
              child: const Text('Send it again'),
            ),
        ],
      ),
      actions: [
        TextButton(
          onPressed: _busy
              ? null
              : () { challenge.cancel(); Navigator.pop(context); },
          child: const Text('Cancel'),
        ),
        FilledButton(
          onPressed: _busy ? null : _verify,
          child: const Text('Verify'),
        ),
      ],
    );
  }
}

Three details that make the difference between a dialog people can use and one they get stuck in:

A wrong code is not the end. For invalid_code, keep the dialog open. For challenge_expired, cancel it and begin a new sign-in. Network and app-auth failures can also arrive through SignInRejected.error.

challenge.method.canResend is false for an authenticator app. That code is computed on their device; offering "send it again" would be a lie.

Give them a way out. On a shared device call verify(code, trustDevice: false). If their second factor is on a phone that is lost or flat, challenge.sendByAnotherMethod(VerificationMethod.email) sends a code somewhere they can reach. Any enrolled factor can answer the challenge.

Step 6 — Show the session, and read something

Wrap the app in the auth stream so it swaps pages by itself:

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: StreamBuilder<AppmintUser?>(
        stream: appmint.auth.changes,
        initialData: appmint.auth.currentUser,
        builder: (context, snapshot) {
          final user = snapshot.data;
          return user == null ? const SignInPage() : SessionPage(user: user);
        },
      ),
    );
  }
}

Then read data as that person. AppEngine has no fixed set of tables — every record has a datatype, and the same call works on all of them, including ones you define:

Future<void> _load() async {
  try {
    final profile = await appmint.http.get('/client-data/profile');
    if (!mounted) return;
    final data = profile is Map ? profile['data'] : null;
    setState(() => _status = data is Map
        ? 'Signed in as ${data['email'] ?? ''}.'
        : 'Unexpected profile response.');
  } on AppmintException catch (e) {
    if (!mounted) return;
    setState(() => _status = e.message);
  }
}

Step 7 — Stay signed in, and sign out

main above already restores once before runApp. If your owner instead restores in initState, expose loading/error state and do not also restore in main. The equivalent call is:

final restored = await appmint.auth.restore();

This reads local state without validating expiry. A protected request must succeed to prove the session is accepted. Cancel auth subscriptions and call appmint.dispose() when the owner closes.

And signing out is one call:

IconButton(
  icon: const Icon(Icons.logout),
  onPressed: appmint.auth.signOut,
)

signOut clears the tokens and the cached person and nothing else. It will not empty your preference store — an app keeps its own settings there, and wiping them on sign-out has in practice left a configured till unable to trade until somebody re-paired the hardware.

Run it

flutter run -d chrome \
  --dart-define=APPMINT_URL=https://appengine.appmint.io \
  --dart-define=APPMINT_ORG=your-org \
  --dart-define=APPMINT_APP_ID=your-app-id \
  --dart-define=APPMINT_DEBUG_TOKEN=your-debug-token

On a real iPhone or a Play-installed Android build, leave APPMINT_DEBUG_TOKEN out; the app proves itself with App Attest or Play Integrity.

What you should see, in order:

  1. A sign-in form.
  2. On Sign in, [appmint] POST /profile/app/challenge and POST /profile/app/attest in the console — the app signing itself in, which you never wrote code for — then POST /profile/customer/signin.
  3. Either the session page, or the verification dialog if the organization asks for a code.
  4. After your profile-read action, the controlled customer’s email. A repository read additionally requires permission for the selected datatype.

When it does not work

What you seeWhat it meansWhat to do
AppmintAppAuthException with a reasonThe app did not sign in. attestation_off: the check is Off. debug_not_allowed / debug_token_invalid: the debug token. proof_unavailable: no App Attest or Play Integrity on this device. Others are listed on Phone apps without a secretFix it in Studio under App Credentials, or use a debug token. Nothing will work until this passes
Could not reach appengine at …The request never left — wrong URL, or nothing listeningCheck APPMINT_URL, including the scheme and no trailing slash
bad passwordThe server refused the sign-inThe credentials are the person's, not the app's
The dialog appears but no code arrivesThe organization sent it to the address on that accountCheck the account's email; on a dev deployment mail may not be delivered at all
That code is not rightWrong code, and the challenge is still aliveLet them retype it — do not close the dialog
That verification session has expiredMore than ten minutes passedStart the sign-in again
Please sign in again mid-sessionThe session could not be renewedExpected after a long gap; send them to sign-in

Set logRequests: true (as above) and every call prints with its status. To put that on screen instead, use appmint.http.onCall — see watching what it does.

Where to go next