Choose the identity that the endpoint expects. AppEngine accepts direct person sessions as well as the application-plus-person flow used by the official clients.
Video tutorials for this topic
| Calling from | Use | Start here |
|---|---|---|
| An operator console (Studio, Business App, Appmint Mobile) | User password sign-in | User authentication |
| A customer-facing site or app (Event App, a storefront) | Customer sign-in / sign-up | Customer authentication |
| A phone app signing itself in (before any person signs in) | App ID + Apple App Attest or Google Play Integrity; no secret | Phone apps without a secret |
| A server, script or integration | API key | API keys |
| A point-of-sale terminal | Passcode or NFC card | POS passcode |
| A hardware hub in a venue | x-hub-key on the WebSocket handshake | hub-agent |
Application and person tokens
The official Flutter transport and the JavaScript server transport send two credentials:
orgid: acme
Authorization: Bearer <app-token>
x-client-authorization: Bearer <person-token>On a server the app token comes from POST /profile/app/key with the App ID and secret. A phone app does not ship the secret; it gets a 1-hour app token from POST /profile/app/challenge and POST /profile/app/attest with Apple App Attest or Google Play Integrity (Phone apps without a secret). A web page, such as 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. The person token comes from staff or customer sign-in, which is the same either way. The second header accepts a raw JWT or a Bearer prefix. A staff person remains a user; a customer remains a customer, even though the middleware stores either secondary identity in currentCustomer.
For a direct staff integration, Authorization: Bearer <staff-token> is also supported. A direct customer bearer is supported on customer routes. Do not infer that every staff-only route accepts an app token simply because a staff token accompanies it: route guards and identity decorators determine which principal is used.
In the JavaScript browser transport, requests go through the configured same-origin proxy; the browser sends the person's token as authorization, and the proxy must attach the app identity and forward the person in x-client-authorization. Do not copy that browser-to-proxy header convention into direct AppEngine requests.
Tenant and session rules
- Send
orgidon tenant operations, normally as a header. Query, body and cookies are also accepted. Public documentation, health checks and certain sign-in/discovery routes are exceptions;publicdoes not generally mean tenant-free. - The middleware verifies signature, issuer, audience, expiry and the record's organization and ID. Changing
orgiddoes not move a session into another tenant. - Primary staff sessions reload the account and use resolved current roles where available. Secondary person tokens still supply their token's roles and permissions. Do not assume every auth path refreshes grants identically.
- Locked staff accounts, revoked primary staff sessions, revoked app credentials (
app_revoked) and blocked/removed devices can invalidate an otherwise unexpired credential. A database lookup failure is a service failure (503), not evidence that the person signed out. - An expired secondary token can continue as anonymous on public operations; an invalid signature is rejected. A successful public request therefore does not prove that a person session is active.
- API keys have enforced scopes and their own identity path; they are neither app credentials nor refresh tokens. See API keys.
Where things live
| Area | Prefix |
|---|---|
| Sign-in, sign-up, invitations, OAuth, blocklists | /profile/* — also mounted at /user/* |
| 2FA, devices, login history, security settings | /profile/security/* |
| API keys and org service users | /api-key/* |
| Integration OAuth callbacks and webhooks | /connect/* |
Reference
- User authentication
- Customer authentication
- API keys
- Two-factor and device security
- OAuth and social login
- Identity and access model — how authorization is actually decided

