appmint_flutter_client is a small package that handles the parts of talking to
AppEngine that are easy to get wrong: authenticating the app itself, keeping two
different tokens on the right headers, and the fact that signing somebody in has
three possible endings rather than two.
Video tutorials for this topic
The six Flutter example apps depend on this package. The larger Appmint Mobile and Event App projects also contain app-local transports; their behavior is not proof of this package’s behavior.
Earlier guidance here was to copy the client pattern into your project rather than depend on a package. That advice cost us: four apps carried four hand-copied clients, and when the server began issuing verification challenges, two of them locked their users out with a sign-in loop. The code is short; the contract is not, and it changes. Depend on the package.
Getting the code
The inspected package declares publish_to: none and version 0.2.0. From 0.2.0 it is a Flutter plugin, with native code for App Attest (ios/) and Play Integrity (android/); Android apps need minimum SDK 24. Its
constraints are Dart ^3.7.0 and Flutter >=3.27.0; choose a Flutter SDK that
also includes the required Dart version. The six examples require Dart
^3.11.0, a stricter requirement than the library itself. Depend on it straight from the repository:
dependencies:
appmint_flutter_client:
git:
url: https://github.com/JacLight/appmint-client.git
path: appmint_flutter_clientPin it to a commit or tag that exists in your checkout when shipping; the placeholder below must be replaced with your reviewed revision:
git:
url: https://github.com/JacLight/appmint-client.git
path: appmint_flutter_client
ref: YOUR_REVIEWED_COMMIT_SHATo read or change the source, clone it and use a path dependency instead:
git clone https://github.com/JacLight/appmint-client.gitdependencies:
appmint_flutter_client:
path: ../appmint-client/appmint_flutter_clientWorking examples live in a second repository — see Example apps.
Your first Appmint app builds a working app from an empty folder in about twenty minutes — sign-in, verification codes, a session and a real read. This page is the map; that one is the walk.
Connect once
final appmint = Appmint(const AppmintConfig(
baseUrl: 'https://appengine.appmint.io',
orgId: 'acme',
appId: 'acme-mobile',
// Simulators, emulators and Flutter web only; empty in a release build.
debugToken: String.fromEnvironment('APPMINT_DEBUG_TOKEN'),
));That is the last time app authentication comes up. Before the first call the
client signs the app in with Apple App Attest (iOS), Google Play Integrity
(Android) or the debug token, through /profile/app/challenge and
/profile/app/attest. It shares one sign-in between concurrent callers, renews
the one-hour app token before it expires and after a 401, and adds orgid
and shared-org-id to normal API requests. Setup in Studio, Xcode and Play
Console is on Phone apps without a secret.
Transport retries also include timeouts and connection resets: a lost response
does not prove that a write failed to reach the server.
Anyone can extract embedded credentials from a mobile binary or web bundle, and an app credential is a System-group user, so the secret carries real authority. appSecret is still accepted, and when it is set the client signs in with /profile/app/key instead of a proof. Use it only in code that runs on your own servers or trusted tools. An app credential whose check is set to Enforce refuses it (reason: "secret_refused").
What it covers
| Area | What you get |
|---|---|
| App authentication | App Attest / Play Integrity / debug-token sign-in, caching, renewal before expiry, retry — invisible |
| Sign-in | Staff and customer, password, magic code, passcode and NFC card |
| Verification | Challenges as a first-class result: verify, resend, switch method, cancel |
| Sessions | Restore at startup, refresh on 401, sign out, a change stream |
| Remembered accounts | One-tap sign-in per organization |
| Data | Reads and writes over any datatype, including your own |
| Anything else | appmint.http — same headers and tokens, any endpoint |
The shape of it
Your widgets → Appmint → auth ──┐
→ repository ──┤→ AppmintHttp → AppEngine
→ http ───────┘ │
SessionStoreAppmint is the one object to hold. It carries the session and the cached app
token, so construct it once and keep it.
No state-management package is imposed. appmint.auth.changes is a plain
Stream<AppmintUser?>; wrap it in whatever your app already uses.
Storage
The default SecureSessionStore writes the active access and refresh tokens
through flutter_secure_storage, and the cached user through shared_preferences.
However, remembered SavedSession records also contain access and refresh tokens,
and the current implementation serializes those records into preferences. Do not
describe all tokens as keystore-only. Implement SessionStore to put remembered
sessions in your own secure store, or use MemorySessionStore when persistence
is not required. Platform storage support must be configured for your target.
Storage keys are global (appmint.access_token, appmint.refresh_token,
appmint.user, appmint.saved_sessions), not namespaced by API origin or org.
A custom store must isolate deployments and users if the app supports multiple
environments. Sign-in persistence is best effort and not awaited; SignedIn
guarantees an in-memory session, not a completed durable write.
Signing out 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.
Configuration and lifecycle
| Option | Default | Meaning |
|---|---|---|
baseUrl | Required | API origin with scheme and no trailing slash |
orgId | Required | Organization for requests; app credentials must match |
appId | Required | The app's public App ID from App Credentials (its record id works too) |
debugToken | '' | A Studio debug token. When set, the app signs in with it instead of App Attest / Play Integrity. Development builds only |
playCloudProjectNumber | null | Android: the Google Cloud project number linked in Play Console, for Play Integrity |
appSecret | '' | Servers and trusted tools only. When set, the client uses /profile/app/key instead of a proof |
appKey | '' | Legacy; unused by AppEngine's sign-in routes |
domainAsOrg | false | Adds domainAsOrg: true on regular API requests |
timeout | 30 seconds | Timeout per regular request attempt |
transientRetries | 4 | Total attempts, including the initial attempt; use at least 1 |
logRequests | false | Console diagnostics; error response excerpts can contain sensitive data |
Initialize Flutter before accessing platform storage. Restore once, retain one client, and dispose it only when its owner is destroyed:
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
final appmint = Appmint(config);
await appmint.auth.restore();
runApp(MyApp(appmint: appmint)); // Your app takes ownership of this instance.
}config and MyApp above are host application definitions. Restore reads local
state without checking the token against the server. A protected request must
succeed before treating that session as server-validated. A stream subscriber
should seed its view with auth.currentUser, because changes is broadcast
and does not replay old events. Cancel subscriptions before appmint.dispose();
disposal closes the auth stream and does not sign out or erase stored tokens.
Offline
The client reads live; there is no cache and no queue of offline actions. What that means for an app that runs in basements and warehouses — and what to do about it — is in Flutter offline and caching.
Related
Current SDK guide and compatibility
The complete repository guide now covers every exposed authentication flow, session lifecycle, generic data helper, HTTP call and upload behavior. Current compatibility was checked against AppEngine source on13 October 2026.
switchOrganization retains the existing app credentials after clearing the session; supply matching credentials and isolated storage for the new org. Remembered sign-in does not switch the configured org, and currently refreshes using the current identity (or customer by default) and reads the last cached user. Do not present cross-user/staff/customer remembered switching as fully verified. Prefer explicit sign-out and normal sign-in until that integration is corrected and tested.
