Verifying an end user #
On this page
Verify the session token on each request to identify the signed-in user. The Account package supports local verification with the realm's public keys and verification through the platform's API.
Your backend verifies each request's session token in one of two ways (The two ways to verify). Local verification, with the realm's keys from TURNZERO_CLOUD_REALM_KEYS, gives the user's id alone. The verification route, POST /accounts/v0/verify, gives the user's addresses, sign-in methods, and standing.
Tell which user sent a request gives the code that does it.
Declaring the accounts service gives your application a separate end-user realm for each environment. It has a production realm, and a development realm too if development is turned on. A person who signs in on the application's hostname has a session in that realm. A development realm has a size limit, and a sign-in that would exceed it is refused development_realm_full; Manage end users states the limit. Sign-in, sessions, and tokens compares the end-user session with the platform's other credentials.
The session cookie contains a signed token #
A signed-in end user has one cookie on the application's own hostname, named __Host-turnzero_cloud_realm. The cookie is host-only, HttpOnly, Secure, and SameSite=Lax, with the path /. Its value is a session token in three parts joined by dots: the prefix turnzero_cloud_usr_1, a payload, and a signature.
A cookie your application sets is host-only too. The router removes any Domain attribute from Set-Cookie to prevent a cookie from reaching sibling application hostnames. It logs removals at most once a minute per environment and router replica, including the cookie name and removed domain, never the cookie value.
The payload is the base64url encoding of a JSON object with seven members:
kid, the identifier of the realm key that signed the token;realm, the realm's identifier;sub, the end user's opaque identifier;jti, a random session identifier;iatandexp, the token's issue and expiry times in seconds; andgen, the user's generation number at the time of signing. Suspending the user withset_end_user_standingadvances it, which ends every session signed before.
The signature covers the UTF-8 bytes of turnzero_cloud_usr_1.<payload>, including the dot after 1. Here <payload> is the token's original base64url payload text. Do not decode and re-encode it, serialize its JSON again, add a newline, or include the final dot and signature. Decode the signature from base64url and verify it with Ed25519 and the realm's public key.
Every realm has its own key pair. The platform keeps the private key and publishes the public keys, as the next sections describe. The token has no algorithm header and accepts no other algorithm; its prefix identifies the version and algorithm.
A test token for your verifier #
To test a verifier you wrote, use the token and public key below. The key is a raw Ed25519 key in base64url. Configure this local test with realm example-realm and key id example-key. The token expired in November 2023 and its realm does not exist, so it signs nobody in.
public_key: 5hkwCmnhUkGiP5mwo5rpfcbMQiqIica3kQ5gRZHgLiE
token: turnzero_cloud_usr_1.eyJraWQiOiJleGFtcGxlLWtleSIsInJlYWxtIjoiZXhhbXBsZS1yZWFsbSIsInN1YiI6ImV4YW1wbGUtdXNlciIsImp0aSI6ImV4YW1wbGUtc2Vzc2lvbiIsImlhdCI6MTcwMDAwMDAwMCwiZXhwIjoxNzAwMDAzNjAwLCJnZW4iOjF9.nXFDL1JZnX9otLtzP2FUb81HxUvGq2BUHq72cFg8LutByrczRWojK4smMHJrCdEoeFsMt3GsnMXv93y5AxVPAw
The payload decodes to {"kid":"example-key","realm":"example-realm","sub":"example-user","jti":"example-session","iat":1700000000,"exp":1700003600,"gen":1}. Your verifier must accept the signature, then refuse the token as expired. Your verifier must also reject the token after any change to a payload character. It may reject invalid JSON, a different realm or an unknown key ID before checking the signature. An Ed25519 check over the prefix, dot and changed payload text must fail.
A session token lasts one hour; the session lasts longer #
The session token expires one hour after it was signed, or at the session's own expiry if that comes first. The session itself lasts the realm's session length, 30 days by default, and the platform keeps a record of it. The token is a signed statement about that record.
When a request arrives with an expired cookie token, the router asks the accounts service to renew it for the same session. The service checks the session and user's standing. If renewal succeeds, the router forwards the request with the new token and sets it as the response cookie. Application code does not handle this renewal; bearer tokens use the native-app refresh flow.
The one-hour expiry applies when the router or a client verifies the token locally with the realm's public keys. The verification route and the realm's own routes, /__account/me among them, check the session record instead. They therefore accept a token past its hour while its session is live. They still check the token against the realm's keys first: a token whose key was deleted is refused session_ended even while its session is live.
An ended session, a suspended user, or a revoked key gets no new token. What happens to the request then depends on the audience:
- On an
invitedorworkforceaudience, a navigation request gets the sign-in redirect, as an unsigned request does. Any other request, including a fetch from a page script, receives 401authentication_required. - On a
publicaudience, the request is forwarded with the header described below set toinvalid. - A token presented as a bearer is refused 401 on every audience, as the section on native apps states.
On a workforce realm, your AI tool signs a test end user in under its own session, and its address carries no source: 'tenant', so a route that reads the tenant mark refuses it. Offline, the Account package's double takes the tenant's place. Its signIn takes a user whose address carries source: 'tenant' and returns that address as given, so a workforce route's signed-in path runs over it (Test with the double).
The two ways to verify #
| Construction | What it gives | When a route needs it |
|---|---|---|
Local verification, with the realm's keys from TURNZERO_CLOUD_REALM_KEYS |
The user's id alone | A route that needs no more than who the user is |
The verification route, with no keys: POST /accounts/v0/verify under the application's credential |
The user's addresses, sign-in methods, and standing | A route that shows the person's details, such as /me |
A native app's backend reads the session token from the Authorization: Bearer header. The verification route accepts that token from your backend as it accepts the cookie's token (Sign in from a native app).
The Account package's verification client, makeVerifyClient, is imported from the npm package @turnzero/account. The client takes one of the two paths, depending on what your application gives it when it is created.
Local verification with the realm's public keys #
Where the environment has a realm, every deploy, promote, and platform redeploy supplies the setting TURNZERO_CLOUD_REALM_KEYS to the container, beside TURNZERO_CLOUD_API. Its value is a JSON object with three members:
realm, the environment's realm identifier;version, the time of the realm's last key change, or 0; andkeys, an array of{ "kid", "public_key" }objects, eachpublic_keya raw 32-byte Ed25519 public key in base64url.
The array is empty before the realm's first sign-in, because the realm's first key is created at that sign-in.
A client created with realm (the environment's realm) and realmKeys (the setting's JSON string, as the environment provides it) verifies a token without a network call. It checks, in order:
- the prefix;
- the payload's
realmagainst the configured realm, never against the token's own claim; - that the set contains a key with the payload's
kidthat is not revoked; and - the signature and the expiry.
If the payload's kid identifies a key the client does not have, the client fetches the realm's current key set and verifies again. The route is the platform's public GET /accounts/v0/realms/<realm>/keys at the TURNZERO_CLOUD_API origin. It needs no credential and returns { "realm", "version", "keys" } for the client's configured realm. The client caches a fetched set for one hour and a failed fetch for ten seconds, and makes at most one fetch at a time per realm.
The signature and expiry checks establish that the platform issued an unexpired token. They cannot detect a later sign-out or revocation on their own. The Account client also checks the router's session header and falls back to the verification API when needed.
The router's session header #
The router sets the header x-turnzero-cloud-session on every forwarded request that includes the session cookie or the token as a bearer, once it has the realm's keys. A request without either gets no header. The router deletes any header of that name the client sent before it sets its own, so the value your application reads is always the router's. The header has two forms:
valid; realm=<realm>; user=<the end user's identifier>; exp=<the token's expiry in seconds>; t=<the first 16 characters of the token's SHA-256 in base64url>;invalid; reason=<a short name>. Examples areuser_revokedafter a suspension withset_end_user_standing,key_revokedafter a key rotation for a compromise, andkey_unknownfor a token whose key the router still does not have.
The header's t value lets the client confirm the header is about this request's token. The header grants nothing by itself. The client accepts a user only on a token it verified locally, and then checks the header, passed on each call as sessionHeader:
- A
validheader whosetmatches the token and whoserealmandusermatch the token's claims accepts the user. - With an
invalidheader, the client refuses the user with the header's reason, even where it still holds an earlier verdict that let that session in. - A missing, malformed, or mismatched header is treated as unknown, and the client falls back to the verification route described next.
The client caches a refusal for ten seconds, keyed by the token's hash.
The router computes the header from the realm's public keys and revocation list. It copies both from the platform when it first sees the realm, then refreshes them every 30 seconds while serving that realm. On an error it keeps the keys and list it already has.
If a token's kid names a key the router does not have, the router copies the realm once more and verifies again. So a person who signs in just after a key rotation or revoke_app_sign_in_keys is accepted on the first request. The router makes that extra copy at most once per realm in ten seconds; a second unknown key id within those ten seconds gets invalid; reason=key_unknown.
A native app presents the token as a bearer #
A native app has the same token as a browser does, obtained at the realm's token endpoint (Sign in from a native app). It sends the token in the Authorization header as Bearer turnzero_cloud_usr_1..... The router treats a bearer of that form as it treats the cookie, verifies it the same way, and sets the same session header on the forwarded request. The bearer takes precedence over a cookie sent beside it. An Authorization header with any other value reaches your application untouched, so your own bearer tokens are unaffected.
A bearer the router cannot verify is refused before your application sees it, on every audience, the public one included. An expired token, a session that ended, a revoked user, and another realm's token are each refused 401 authentication_required with the header WWW-Authenticate: Bearer error="invalid_token". The router never renews a bearer; the app refreshes at the token endpoint before the hour passes. Each refused bearer counts once against the sender's client address under the per-address limit, and bad bearers past that limit are refused rate_capped.
The response's detail identifies a router-generated 401.
The verification route #
A client created with neither realm nor realmKeys uses only the verification route. It sends POST /accounts/v0/verify to the platform under the application's credential TURNZERO_CLOUD_APP_TOKEN, with a JSON body whose session member is the cookie's value. Calling the verification route directly gives the whole request, the response's members, and every refusal. The client caches a successful response for the shortest of three times: its configured interval (60 seconds by default), the route's cache_until, and the session's expiry. An application that verifies through the route needs no key set and can leave TURNZERO_CLOUD_REALM_KEYS unread.
The application's credential belongs to one environment and selects that environment's realm. A credential that belongs to no environment, an account-wide credential or a minted token, names the environment with the header x-turnzero-cloud-environment or the body member environment. Naming neither is refused 400 environment_required. A header and a body member that disagree, or another environment than a platform credential's own, are refused 403 environment_mismatch.
A local run presents the development credential. On an application with one environment, which has no development realm, the route checks that credential's sessions against production's realm, the application's only list of end users. It checks a session someone already has, and starts none. With development turned on, each credential reaches its own environment's realm alone.
The route checks a token against the realm's keys before it checks the live session:
- A token signed by a key that
revoke_app_sign_in_keysrevoked is refusedsession_revoked. - A token whose signature fails, or whose key the realm no longer has, is refused
session_ended.
A session of another realm is refused session_other_realm, whether it is live, signed out, or expired. The response tells your backend nothing else about that session.
Every verification through the route is counted as a backend action in read_usage and has no per-request charge. A request the router verified locally counts once, as the forwarded request, and not as a verification.
The token contains the user's identifier, the realm, and the generation number, and none of the user's addresses, sign-in methods, or standing. So a backend that verifies locally and needs a user's verified email keeps a second client without the keys for that read alone, as Tell which user sent a request shows. A work-account user's address is marked source: "tenant", and is verified only where the tenant's token includes the claim xms_edov, the domain owner's verification, as true.
A backend without the Account package calls the route itself, as Calling the verification route directly shows.
Signing-key rotation and revocation #
A realm's keys rotate without any step from you. At each sign-in or token renewal, the platform checks the age of the realm's newest key. If it is older than 180 days, the platform creates a new key and retires the previous one. A retired key still verifies the tokens it signed for one hour plus one day, and is then deleted. The verification client fetches the new key the first time a token refers to it, and the next deploy or promote supplies the current set. Nothing in your application changes.
revoke_app_sign_in_keys is the management action for a suspected compromise of a realm's signing key. It takes application and environment. It is a reversible action, so it needs no browser approval. It revokes every signing key of the realm, and the accounts service creates the realm's next key at its next sign-in.
A revoked key verifies nothing and signs no new token. Every session it signed ends at its next request, and the router's header becomes invalid; reason=key_revoked. A client that still has the old key set refuses the token through the header. A client that verifies through the route meets session_revoked there. Each user signs in again.
What a sign-out or a revocation does #
These actions end sessions:
- the user's sign-out,
POST /__account/signouton the application's hostname; - the user's ending of one of their own sessions, the presenting one included,
POST /__account/sessions/<id>/revokeon the application's hostname; - a native app's revocation call,
POST /__account/oauth/revoke; set_end_user_standingwithstanding: suspended;- a sign-in that would open a user's 101st live session, which ends the user's oldest;
- deleting an end user; and
- deleting the realm, with its environment or its application.
Each writes an entry on the realm's revocation list together with its own change. The routers pick up the entry within their 30-second copy interval. Within a minute, the router rejects the ended session or marks it invalid, according to the audience and whether the request uses a cookie or bearer token. The Account client rejects a forwarded request marked invalid. The platform also does not renew the token, so an ended session does not outlast its token.
set_end_user_standing with standing: active restores a suspended user's standing and allows a new sign-in. The ended sessions stay ended.
The revocation list keeps one hour of endings, the token's life. After that hour every token of an ended session has expired, and the platform does not issue a new one. During an outage of the platform's management services, the routers keep the keys and list they have. A revocation made during the outage reaches them when those services return.
Current values #
| Value | Current setting |
|---|---|
| The token life | one hour |
| The routers' copy interval for keys and revocations | 30 seconds |
| The router's wait between two extra copies for an unknown key id, per realm | 10 seconds |
| The key rotation interval | 180 days |
| The client's refusal cache | 10 seconds |
| The client's key-set cache, and its cache of a failed fetch | one hour, and 10 seconds |
| The verification route's client cache, by default | 60 seconds |
| The realm's session length | 30 days by default; configure_app_sign_in's session_days sets 1 to 30 |
The platform sets the token life, the copy interval, and the rotation interval, and can change them without any change to your application. The session length is yours, for sessions opened after the configure_app_sign_in call (Manage end users). The client's caches are constants of the Account package's client, and change only when your application takes a new package version; the route cache's interval is also the client's cacheSeconds option.
Related #
- Tell which user sent a request holds the code that verifies a request, from the cookie or the bearer.
- Manage end users covers the realm's sign-in methods, invitations, revocation, and reinstatement.
- Sign-in, sessions, and tokens compares the end-user session with the platform's other credentials.
- Account is the package page for the verification client and the accounts service.
- Applications and environments explains the two hostnames and when the development realm's sign-in pages exist.
- Actions lists
revoke_app_sign_in_keys,set_end_user_standing, and the other end-user actions with their payloads.