docs
/
AppEngine API

Choosing an auth method

Which credential to use for which kind of client.

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.

Calling fromUseStart here
An operator console (Studio, Business App, Appmint Mobile)User password sign-inUser authentication
A customer-facing site or app (Event App, a storefront)Customer sign-in / sign-upCustomer authentication
A phone app signing itself in (before any person signs in)App ID + Apple App Attest or Google Play Integrity; no secretPhone apps without a secret
A server, script or integrationAPI keyAPI keys
A point-of-sale terminalPasscode or NFC cardPOS passcode
A hardware hub in a venuex-hub-key on the WebSocket handshakehub-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 orgid on 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; public does not generally mean tenant-free.
  • The middleware verifies signature, issuer, audience, expiry and the record's organization and ID. Changing orgid does 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

AreaPrefix
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