The first real decision in any integration is what the caller is. Not what it does — what it is. A member of staff, a customer of yours, a server, a till, a piece of hardware in a venue. AppEngine has a different mechanism for each, and the common failure is reaching for a staff login because it is the one you already have.
Pick by caller, not by convenience
| The caller | What it uses |
|---|---|
| A person on your team | User sign-in |
| A customer of yours, on your site or app | Customer sign-in — a separate identity space |
| A server, script or integration | An API key |
| A point-of-sale terminal | A passcode or an NFC card |
| A hardware hub in a venue | A key on the WebSocket handshake |
Customers are deliberately not users. Giving a customer a staff account to solve a login problem grants them a permission surface you did not intend, and no amount of role editing afterwards makes that clean.
Two headers, always
Every authenticated request carries the bearer token and the tenant. The tenant is not implied by the token, and omitting it produces a different failure than being unauthenticated — one that reads as a permissions problem when it is not.
Authorization: Bearer eyJhbGciOi…
orgid: acmeThe token is the user record
The JWT payload is the signed user, which is why middleware can read the id, datatype and roles without a lookup. Two consequences are worth holding on to:
- The user is re-fetched from the org database on every request. A revoked account fails immediately with
401. - Roles and permissions are copied from the token onto that record. A role changed after the token was issued still applies until the token refreshes.
If you need a permission change to bite immediately, force a refresh rather than assuming the next request picks it up.
Sign-in can succeed without signing you in
Three responses return successfully and hand you no token. Treat them as first-class paths, not error handling:
- A temporary password — the caller must set a real one before anything else.
- Two-factor — you get a challenge token and a method of email, SMS or authenticator. For the first two the code has already been sent.
- An unrecognized device — when the org has new-device authentication on, a fingerprint it has not seen triggers the same challenge flow.
API keys are for machines
A server has no password to rotate and no second factor to satisfy. Give it a key, scope it, and keep it out of anything that ships to a browser. Keys are records like anything else, which means they can be listed, rotated and revoked without a deploy.
Terminals and hardware
A till in a shop is used by several people through a shift and cannot ask for an email address each time. It authenticates with a passcode or an NFC card against a staff identity. A hardware hub is not a person at all and presents a key on the WebSocket handshake instead.
Read next
- Authentication overview — the full decision table
- API keys — scoping and rotation
- Two-factor and devices
- Identity and access — how this sits in the platform