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.
Video tutorials for this topic
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.
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 chromeThe 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_appStep 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_clientflutter pub getStep 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.
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-tokenOn 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:
- A sign-in form.
- On Sign in,
[appmint] POST /profile/app/challengeandPOST /profile/app/attestin the console — the app signing itself in, which you never wrote code for — thenPOST /profile/customer/signin. - Either the session page, or the verification dialog if the organization asks for a code.
- 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 see | What it means | What to do |
|---|---|---|
AppmintAppAuthException with a reason | The 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 secret | Fix 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 listening | Check APPMINT_URL, including the scheme and no trailing slash |
| bad password | The server refused the sign-in | The credentials are the person's, not the app's |
| The dialog appears but no code arrives | The organization sent it to the address on that account | Check the account's email; on a dev deployment mail may not be delivered at all |
| That code is not right | Wrong code, and the challenge is still alive | Let them retype it — do not close the dialog |
| That verification session has expired | More than ten minutes passed | Start the sign-in again |
| Please sign in again mid-session | The session could not be renewed | Expected 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.
