---
title: Verifying an end user
description: Learn how an application's backend verifies who is signed in: the session token, local verification, the router's header, and the verification route.
slug: /concepts/verifying-an-end-user
order: 10
visibility: public
redirects_from: []
---

# Verifying an end user

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](#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](/cloud/guides/add-sign-in-to-your-app/#3-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](/cloud/guides/manage-end-users/) states the limit. [Sign-in, sessions, and tokens](/cloud/concepts/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;
- `iat` and `exp`, the token's issue and expiry times in seconds; and
- `gen`, the user's generation number at the time of signing. Suspending the user with `set_end_user_standing` advances 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.

```text
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](/cloud/concepts/glossary/#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](/cloud/concepts/glossary/#audience):

- On an `invited` or `workforce` audience, a navigation request gets the sign-in redirect, as an unsigned request does. Any other request, including a fetch from a page script, receives 401 `authentication_required`.
- On a `public` audience, the request is forwarded with the header described below set to `invalid`.
- 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](/cloud/guides/test-sign-in-with-test-end-users/) 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](/cloud/backend-packages/account/#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](/cloud/guides/sign-in-from-a-native-app/#5-call-the-backend-with-the-bearer)).

The [Account package](/cloud/backend-packages/account/)'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](/cloud/concepts/glossary/#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; and
- `keys`, an array of `{ "kid", "public_key" }` objects, each `public_key` a 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:

1. the prefix;
2. the payload's `realm` against the configured realm, never against the token's own claim;
3. that the set contains a key with the payload's `kid` that is not revoked; and
4. 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 are `user_revoked` after a suspension with `set_end_user_standing`, `key_revoked` after a key rotation for a compromise, and `key_unknown` for 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 `valid` header whose `t` matches the token and whose `realm` and `user` match the token's claims accepts the user.
- With an `invalid` header, 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](/cloud/guides/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](/cloud/concepts/egress-firewall-and-request-limits/#the-per-address-and-per-user-limits), 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](/cloud/backend-packages/account/#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](/cloud/concepts/glossary/#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_keys` revoked is refused `session_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](/cloud/guides/add-sign-in-to-your-app/#3-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](/cloud/backend-packages/account/#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/signout` on the application's hostname;
- the user's ending of one of their own sessions, the presenting one included, `POST /__account/sessions/<id>/revoke` on the application's hostname;
- a native app's revocation call, `POST /__account/oauth/revoke`;
- `set_end_user_standing` with `standing: 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](/cloud/concepts/glossary/#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](/cloud/guides/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](/cloud/guides/add-sign-in-to-your-app/#3-tell-which-user-sent-a-request) holds the code that verifies a request, from the cookie or the bearer.
- [Manage end users](/cloud/guides/manage-end-users/) covers the realm's sign-in methods, invitations, revocation, and reinstatement.
- [Sign-in, sessions, and tokens](/cloud/concepts/sign-in-sessions-and-tokens/) compares the end-user session with the platform's other credentials.
- [Account](/cloud/backend-packages/account/) is the package page for the verification client and the accounts service.
- [Applications and environments](/cloud/concepts/applications-and-environments/) explains the two hostnames and when the development realm's sign-in pages exist.
- [Actions](/cloud/reference/action-catalog/) lists `revoke_app_sign_in_keys`, `set_end_user_standing`, and the other end-user actions with their payloads.
