docs
/
Client Integration

Flutter client

The package that talks to AppEngine from Flutter — app authentication, staff and customer sign-in, and reads and writes over any datatype.

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.

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.

This used to say "own it outright"

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_client

Pin 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_SHA

To read or change the source, clone it and use a path dependency instead:

git clone https://github.com/JacLight/appmint-client.git
dependencies:
  appmint_flutter_client:
    path: ../appmint-client/appmint_flutter_client

Working examples live in a second repository — see Example apps.

New here? Start with the tutorial.

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.

Do not release a phone app with the secret

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

AreaWhat you get
App authenticationApp Attest / Play Integrity / debug-token sign-in, caching, renewal before expiry, retry — invisible
Sign-inStaff and customer, password, magic code, passcode and NFC card
VerificationChallenges as a first-class result: verify, resend, switch method, cancel
SessionsRestore at startup, refresh on 401, sign out, a change stream
Remembered accountsOne-tap sign-in per organization
DataReads and writes over any datatype, including your own
Anything elseappmint.http — same headers and tokens, any endpoint

The shape of it

Your widgets  →  Appmint  →  auth  ──┐
                          →  repository ──┤→  AppmintHttp  →  AppEngine
                          →  http  ───────┘        │
                                                SessionStore

Appmint 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

OptionDefaultMeaning
baseUrlRequiredAPI origin with scheme and no trailing slash
orgIdRequiredOrganization for requests; app credentials must match
appIdRequiredThe 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
playCloudProjectNumbernullAndroid: 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
domainAsOrgfalseAdds domainAsOrg: true on regular API requests
timeout30 secondsTimeout per regular request attempt
transientRetries4Total attempts, including the initial attempt; use at least 1
logRequestsfalseConsole 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.

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.