This page is about the person's sign-in, which is the same however the app itself signs in. For the app's own sign-in on a phone, without the secret, see Phone apps without a secret.
Video tutorials for this topic
Two identities, kept apart
AppEngine has two kinds of people and they are different records with different
sign-in routes. The client keeps them visible rather than hiding the difference
behind one signIn:
appmint.staff.signIn(email, password); // employees, managers, admins
appmint.customers.signIn(email, password); // the people you serveThey are not interchangeable, and some routes behave differently for each — a staff account with no matching customer record cannot reach the security routes at all. Picking the wrong one produces confusing failures rather than a clean refusal, so choose deliberately.
Sign-in has three endings
It does not return a token. It returns a sealed result, and the compiler makes you handle every case:
switch (await appmint.customers.signIn(email, password)) {
case SignedIn(:final user):
// there is a session — go
case NeedsVerification(:final challenge):
// the password was right; a code is needed
case SignInRejected(:final message):
showError(message); // the server's own wording, safe to show
}A verification challenge arrives as an ordinary 200 with no token in it.
Two shipped apps read that as success, stored an empty token, and threw people
out on the first real request — a sign-in loop that never mentioned the code
that had just been emailed. As a result type, forgetting that case is a build
error instead of an outage.
Finishing a verification
The challenge carries everything needed, including the way out when the second factor is on a phone that is lost or flat:
case NeedsVerification(:final challenge):
challenge.method; // email | sms | authenticator
challenge.message; // the server's sentence
challenge.isNewDevice; // challenged because the device is unrecognised
challenge.sentTo; // where it went, when it went anywhere
final result = await challenge.verify(code); // trustDevice: true by default
await challenge.resend();
await challenge.sendByAnotherMethod(VerificationMethod.email);
challenge.cancel();verify returns the same three-way result. Inspect SignInRejected.error?.reason:
invalid_code permits another attempt; challenge_expired needs a new sign-in.
A rejection is not always a wrong code: error can also be an
AppmintNetworkException or AppmintAppAuthException. Some malformed successful
responses produce a rejection with error == null.
resend() and sendByAnotherMethod() return Future<bool> and catch failures.
Only show “code sent” for true; this acknowledges the request, not delivery.
Changing the method updates challenge.method but not its immutable message
or sentTo. cancel() only clears the current HTTP user token; it does not
revoke the challenge on the server, clear storage, or emit a sign-out event.
Two details worth honouring in your UI:
challenge.method.canResendis false forauthenticator. That code is computed on the device; offering "send it again" would be a lie.- Any factor the account has enrolled can answer the challenge, so
sendByAnotherMethodonly changes how the code arrives. It is the difference between a locked-out user and a mildly inconvenienced one.
trustDevice defaults to true and is sent to the backend. Use false on a
shared terminal. Whether a later request is recognized depends on the backend’s
device/cookie contract; this SDK does not itself install a persistent device ID
or cookie jar, so passing the flag alone does not prove future challenges stop.
Signup and user fields
final result = await appmint.customers.signUp(
email: email,
password: password,
firstName: 'Alex',
lastName: 'Reader',
);Both identities expose signUp, but deployment policy determines whether their
routes allow registration. The result still requires all three branches.
AppmintUser exposes id, email, name, displayName, phone, avatar, and
identity. raw contains the inner data map when present, not the complete
record envelope; retain separately fetched records if you need root metadata.
The other ways in
await appmint.customers.sendMagicCode(email);
await appmint.customers.verifyMagicCode(email, code);A magic code replaces the password rather than adding to it.
await appmint.staff.signInWithPasscode(employeeId: '4471', pin: '123456');
await appmint.staff.signInWithPasscode(employeeId: '4471', cardUid: uid);Passcode and NFC card sign-in are for shared devices — a till, a host stand, a door scanner — where typing a password in front of a queue is the slowest thing in the building. The server deliberately exempts them from verification challenges so service is never interrupted, which also makes them the way back in when an organization has just switched two-factor on.
Staying signed in
await appmint.auth.restore(); // once at startup; loads local state only
appmint.auth.currentUser;
appmint.auth.isSignedIn;
appmint.auth.changes.listen(...); // sign-in, sign-out, forced sign-out
await appmint.auth.signOut();restore() reads the stored tokens and user without an HTTP call or expiry
check. Missing user data causes local sign-out. A restored user is not evidence
that the server still accepts the session.
The app token from app/attest lasts one hour; the client renews it before it expires by signing the app in again. A revoked app credential's token is refused with 401 and code: "app_revoked".
On the first 401, normal HTTP requests fetch another app token and attempt a
user-token refresh when a user token is attached. They retry the request once.
A second 401 with a user token clears it, emits null, and throws
AppmintSessionExpiredException. App-token acquisition can itself fail before
that point. Other statuses do not trigger refresh.
await appmint.auth.refreshSession() explicitly attempts renewal for a socket
handshake; it returns a token or null. It catches refresh failures and does
not automatically sign out when returning null. Use a sign-in recovery state
when renewal fails instead of reconnecting indefinitely.
signOut() is local: it clears the active token/user and emits null; it does
not call a server revocation endpoint. Remembered accounts survive. The default
store and persistence limitations are documented under Storage.
Remembered accounts
final saved = await appmint.auth.savedSessions(); // newest first
await appmint.auth.forgetSession(email, orgId); // does not sign outEntries are deduplicated by (email, orgId), not by org alone or by identity.
Their expired flag is set when signInWithSaved cannot renew them; ordinary
startup restore does not set that flag.
The current signInWithSaved(session) implementation has integration limits:
it does not change the configured org, derives refresh identity from the current
user (defaulting to customer), and reads the existing cached user instead of
fetching the selected account's profile. It also does not explicitly replace
the HTTP access token with the renewed token. Do not build a production account
switcher that assumes this method establishes the selected staff identity.
Prefer an explicit org switch and fresh sign-in until that flow has been fixed
and tested against your deployment.
Changing organization
await appmint.switchOrganization('other-org');This ends the current session on purpose: a token issued for one organization is not valid for another. The cached app token is dropped too, so the next call authenticates against the new one.
What is not here
No biometric unlock, and no second factor the client invents on its own — the
only codes are the ones AppEngine issues. If an organization turns on two-factor
or new-device verification, NeedsVerification is how it reaches you.

