A custom web application normally sends two independent identities to AppEngine:
Video tutorials for this topic
| Identity | Server-to-AppEngine header | Owner |
|---|---|---|
| Application | Authorization: Bearer <app-token> | Your server's integration |
| Customer | x-client-authorization: <customer-token> | One signed-in visitor |
| Organization | orgid: <org-id> | Trusted deployment or tenant resolution |
Public routes can allow an anonymous visitor. Customer-only routes still need that visitor's session; an application token is not a shopper. Staff-only operations need an authorized staff identity and must not be exposed through the storefront proxy. A tenant label alone grants no access.
Application exchange
The JS client sends this request from the server:
/profile/app/keyThe current controller consumes appId, secret, and optional domain; the current JavaScript working tree requires appId and appSecret before attempting the exchange; appKey is optional. Flutter still requires an appKey constructor argument, which may be empty when registration did not issue a legacy key. Keep all application credentials and the resulting token server-side. The SDK caches the token on its instance, while the Next.js/Remix example transports cache it in their server module.
POST /profile/app/key is for servers, where the secret can be kept. An iPhone or Android app ships only the org ID and App ID, and gets its app token from POST /profile/app/challenge and POST /profile/app/attest with Apple App Attest or Google Play Integrity. A web page (the site chat widget) gets it from app/attest with platform: "web" and the website it is on, which must be one of the app's Allowed domains. That token travels in Authorization: Bearer exactly like the one above and lasts one hour. See Phone apps without a secret. When an app credential's check is set to Enforce, app/key refuses the secret with 401 and reason: "secret_refused".
A revoked app credential's tokens are refused on every request with 401 and code: "app_revoked", not only at the next exchange. POST /profile/guest/auth needs this app's token as the bearer token; without it the answer is 401 with code: "app_token_required".
Wherever a route takes appId (app/key, app/challenge, app/attest, the appId header of guest/auth), the app credential's record id works as well as its App ID (username).
A server-side resource 401 triggers one application-token renewal and replay. This is not customer refresh. A 403 is permission failure; a network/503 failure is availability failure. Neither should automatically erase a valid visitor session.
Establish the visitor session
Your own login route accepts the visitor's credentials, calls POST profile/customer/signin, and interprets the result. The route name in your application is your choice; /api/user/customer/login is not an SDK-generated route.
// Server code; createClient factory is defined in the TypeScript reference.
import { clientForRequest } from './appmint.server';
type SignInResult = {
token?: string;
refreshToken?: string;
requiresTwoFactor?: boolean;
challengeToken?: string;
twoFactorMethod?: string;
message?: string;
};
export async function authenticate(email: string, password: string) {
const client = clientForRequest();
const result = await client.post<SignInResult>(
'profile/customer/signin', { email, password },
);
if (result.requiresTwoFactor) return { kind: 'challenge' as const, result };
if (!result.token) throw new Error('Sign-in returned no customer token');
return { kind: 'authenticated' as const, result };
}Complete a challenge before creating an authenticated session. The public security endpoints take the challenge credential itself:
await clientForRequest().post('profile/security/challenge/send', {
challengeToken, method: 'email',
});
const verified = await clientForRequest().post<SignInResult>(
'profile/security/challenge/verify', { challengeToken, code, trustDevice: false },
);
if (!verified.token) throw new Error('Verification returned no customer token');These are fragments in your server's challenge handlers: challengeToken comes from the pending session and code from the visitor. Use the offered method; an authenticator challenge does not need an email resend. Store the returned token and refreshToken using your session policy, then discard the challenge credential. The JS SDK has no challenge helper, and its auth.signIn response type exposes only optional token; use a typed generic request when you need the other fields. auth.signIn stores a token only in memory on that client instance.
Your server owns persistence: use a framework session store with an opaque HTTP-only cookie, or an HTTP-only token cookie if that is your chosen design. For production cookies set Secure, HttpOnly, SameSite=Lax or stricter as appropriate, and Path=/; enforce same-origin/CSRF checks on mutations. Do not return the token in browser-readable login JSON when using this design. Keep refresh/challenge values in the server-side session and never in URLs or logs.
On each later request, read that request's session, create a client, call setCustomerToken(token), and discard the instance afterward. Never mutate a module-global customer client. The Next.js example reads appmint_token in its proxy, and Remix's pricing action reads the same cookie name, but neither demo ships a login route that creates it.
Browser transport versus example cookies
The SDK browser transport forwards an explicitly configured customer token as authorization and includes same-origin cookies. The example Next.js proxy reads the cookie only; it does not consume that browser authorization header. Pick one deliberate session mechanism and implement both ends. In the cookie design, browser code simply calls your route and never calls setCustomerToken.
Separate browser configuration from server credentials. typeof window selects a transport; it cannot remove a secret that was already compiled into a bundle.
Read, refresh and end the session
Use GET client-data/profile to read the current customer. The SDK's auth.profile() currently calls a missing parameterless route; profile/customer/profile/:emailOrUsername is a different endpoint and is not the customer-self API.
Customer refresh is POST profile/customer/refresh with { "refresh_token": "<refresh-token>" }. The request uses snake-case refresh_token; the response uses token and refreshToken. Store replacement credentials according to that response. The JS client does not call it automatically. Clearing setCustomerToken(null) clears only that instance; logout must also clear your own session/cookie and apply any backend session-ending behavior your app uses.
Verify two separate customer sessions concurrently. Customer A's profile/orders must remain A's, B's must remain B's, and an anonymous request must not inherit either. Test a stale customer token separately from an expired application token.
Domain resolution and telemetry
For a single tenant, configure orgId on the server. For multiple hosts, resolve a permitted hostname to its organization before constructing a client; do not trust a browser-supplied orgid as authority. The SDK's domainAsOrg flag and shared-org-id header alone are not a complete multi-domain gateway. The hosted renderer has additional host and telemetry handling; see server proxy and browser runtime.

