---
title: Account
description: Add end-user sign-in, sessions, and access recovery to an application, and verify a session from its backend, in one realm per environment.
slug: /backend-packages/account
order: 4
visibility: public
redirects_from: []
---

# Account

The Account package gives your application's end users their own accounts, which are not Turn Zero accounts. You do not build identity infrastructure yourself. It covers account creation, sign-in, sign-out, sessions that last across visits, and access recovery. When your [manifest](/cloud/concepts/glossary/#manifest) declares the accounts service, the platform creates one end-user [realm](/cloud/concepts/glossary/#realm), the list of an environment's end users, for each environment your application has. An application with one environment has one realm, production's, and your testers sign in there, also during a [local run](/cloud/concepts/glossary/#local-run). With a development environment added, a sign-in to the development realm never reaches production's users.

To use it, add `{"kind": "accounts"}` to the manifest's `services` and submit the manifest with `submit_manifest`. Your backend then uses the package's client, described in [The client](#the-client), to tell which user sent each request. [Tell which user sent a request](/cloud/guides/add-sign-in-to-your-app/#3-tell-which-user-sent-a-request) shows how.

To send a person back to the page they came from after signing in, see [Choose where sign-in returns](/cloud/guides/add-sign-in-to-your-app/#choose-where-sign-in-returns).

At a glance:

- **Install:** run `turnzero library take --entry account` (`turnzero.cmd` in Windows PowerShell) at the project's root. [Use the library](/cloud/guides/use-the-library/#3-add-an-entry-to-the-library-folder) shows the dependency and manifest entries the command writes. Then [put the copy in a deploy](/cloud/guides/use-the-library/#put-the-copy-in-a-deploy).
- **Manifest:** add `{"kind": "accounts"}` to `services`.
- **[Settings your server reads](/cloud/concepts/the-settings-a-deployed-copy-receives/):** `TURNZERO_CLOUD_API`, `TURNZERO_CLOUD_APP_TOKEN`, and, in a deployed copy, `TURNZERO_CLOUD_REALM_KEYS`.
- **Import:** `import { makeVerifyClient } from '@turnzero/account';`
- **The client:** `makeVerifyClient({ baseUrl, credential, realmKeys })`, built once from the three settings, with `realmKeys` left out where its setting is unset or the route needs the user's email address ([Construction and options](#construction-and-options)).
- **The check:** `client.verifySession(session, { sessionHeader })` returns `{ user }` for a live session, `{ anonymous: true }`, or `{ refused }` ([Methods and results](#methods-and-results)). [Tell which user sent a request](/cloud/guides/add-sign-in-to-your-app/#3-tell-which-user-sent-a-request) has the whole server.

## Use it when

Use Account when your application must recognize a person across sessions, protect personal data, or tie records to one end user.

Do not add it only to remember a local preference or an anonymous device. Those needs do not justify an identity service.

## What it provides

- Account creation and sign-in.
- Sessions: creation, persistence, and sign-out.
- Access recovery.
- Verification of an end-user session from your application's backend, through the client described in [The client](#the-client).
- The end-user identity that other packages depend on.
- A [test double](/cloud/concepts/glossary/#test-double), `createAccountDouble` at `@turnzero/account/testing`, which signs users in and out in memory behind the unchanged client. [Test with the double](#test-with-the-double) shows it in use.

The package stores no per-account settings. Keep your application's preferences in the [Database](/cloud/backend-packages/database/) package. [Manage end users](/cloud/guides/manage-end-users/) covers the realm's settings, its passkeys and their notices, and its end-user actions.

## Availability

Version 0.23.3 is the package's current version, and this page describes it. Until the library's next publish, `read_library` can return an earlier version without every change described here. Use the version it returns. The entry includes the `testing` subpath. It also contains the compiled `makeVerifyClient` as `@turnzero/account`, the [product statement and detailed contract](/cloud/concepts/glossary/#product-statement-and-detailed-contract), and the integration guide.

## Related feature packages

[Verifying an end user](/cloud/concepts/verifying-an-end-user/) explains how a backend verifies a session. [Manage end users](/cloud/guides/manage-end-users/) explains the realm's configuration and its end-user actions.

## The client

The package is published in the library as the npm package `@turnzero/account`, not on the npm registry; [Use the library](/cloud/guides/use-the-library/#5-install-a-package-s-compiled-code) installs it with one line. Import `makeVerifyClient` from `@turnzero/account`. Install `@types/node` if your application type-checks against the client's declarations, because they import Node's built-in modules. [Tell which user sent a request](/cloud/guides/add-sign-in-to-your-app/#3-tell-which-user-sent-a-request) shows the client in a complete server, from an incoming request to the user's id. [Verifying an end user](/cloud/concepts/verifying-an-end-user/) explains the session token the client checks.

### Construction and options

The function `makeVerifyClient(options)` returns a client. Build it once and keep it, because each client has a cache of its own.

Pass `realmKeys` where the route needs only the user's id. Leave it out where the route needs the user's email address, sign-in methods, or [standing](/cloud/concepts/glossary/#standing), because a session verified with keys has none of them.

Leave it out too for a route that needs both the id and the email address on every request, because the verification route's response includes both. Each verification then has no per-request charge, and the client reuses a verdict for up to `cacheSeconds`.

| Option | Default | Meaning |
| --- | --- | --- |
| `baseUrl` | Required | The platform's origin, from the setting `TURNZERO_CLOUD_API`. |
| `credential` | Required | The application's platform credential, from `TURNZERO_CLOUD_APP_TOKEN`, sent as the bearer on each verification. |
| `realmKeys` | None | The realm's public keys: the `TURNZERO_CLOUD_REALM_KEYS` string, or an array of `{ kid, publicKey }`. A malformed value throws at construction. |
| `realm` | The `realm` of `realmKeys` | The environment's realm, the one every token is checked against. |
| `cacheSeconds` | 60 | The longest a verdict is reused; 0 turns reuse off. |
| `transport` | The global `fetch` | The fetch-shaped function the client sends its requests through, such as the test double's `transport`. |
| `keyFetch` | The platform's key-set route | How the client reads the realm's current keys, when a token refers to a key the client does not have or its keys are an hour old. |
| `ownerAccount` | None | Your Turn Zero account's id, for `verifyOwner`. Read it through your own connection's `read_account`, as [Methods and results](#methods-and-results) explains. |
| `now` | `Date.now` | The clock, in milliseconds, for tests. |

The two ways to build it:

- **Local verification.** For the user's id alone, build it with `realmKeys` from `TURNZERO_CLOUD_REALM_KEYS`, which every deploy, promote, and [platform redeploy](/cloud/concepts/glossary/#platform-redeploy) sets, and pass each request's `x-turnzero-cloud-session` header as `sessionHeader`. The client checks the token in your process, and the router's header tells it whether the session ended. When the client accepts a session locally, the user it returns has empty `addresses` and `routes`, because the token has neither. [Tell which user sent a request](/cloud/guides/add-sign-in-to-your-app/#3-tell-which-user-sent-a-request) shows a second client, built without keys, that reads the verified email.
- **[The verification route](#calling-the-verification-route-directly).** For the user's addresses, sign-in methods, or [standing](/cloud/concepts/glossary/#standing), build it without `realmKeys`. It sends the session to `POST /accounts/v0/verify` under the credential, and each verification has no per-request charge. In a local run of an application with one environment, the route accepts the development credential for production's realm. It checks a session a tester already has, and does not open a new one.

### Methods and results

#### Verify a session

The `verifySession(session, { sessionHeader })` method takes the session token the request sent. That is the value of the cookie `__Host-turnzero_cloud_realm`, or the token after `Authorization: Bearer ` from a native app. A native app gets that token as the `access_token` of the realm's token endpoint, whose members [Sign in from a native app](/cloud/guides/sign-in-from-a-native-app/#3-run-the-sign-in-and-exchange-the-code) lists. The client reads no header and no cookie itself.

Pass the request's `x-turnzero-cloud-session` header as `sessionHeader`; it contains the serving router's session verdict. Only a client configured with `realm` or `realmKeys` reads it. A client with neither ignores it and uses the verification route. An `invalid` header refuses the session immediately, even after a cached success. [The router's session header](/cloud/concepts/verifying-an-end-user/#the-router-s-session-header) describes both forms. `verifySession` returns a promise of one of three verdicts:

| Verdict | When |
| --- | --- |
| `{ user, verifiedAt, cacheUntil, sessionExpires }` | The session is live. Its `user` has `id`, `realm`, `addresses`, `routes`, and `standing`, `active` or `suspended`. |
| `{ anonymous: true }` | No session was passed. The client makes no request. |
| `{ refused, detail }` | The session was refused, and `refused` gives the reason. |

Each address is `{ email, verified }`. A user who signed in only with a work account has, on the verification route, the address the company's tenant asserts, with `source: "tenant"`. The optional `xms_edov` token claim indicates whether the email domain's owner has been verified. The address is `verified: true` only where that claim is true and no other account already has the address verified. Otherwise it is `verified: false`. Read `verified` before relying on the address.

#### Verify the application's owner

`verifyOwner` is for a script or tool holding a Turn Zero token minted under your account. A web page never collects that credential.

The `verifyOwner(bearer)` method checks your application's owning account through `read_account`, returning `{ owner: { id } }` on a match or `{ anonymous: true }` without a bearer. Refusals are `owner_not_configured` without `ownerAccount`, or `not_owner` when the returned account differs. It also returns `read_account`'s refusal name, such as `authentication_required` for a bad bearer, or `http_<status>` when the answer names none. It reads no session token. It needs no accounts service declared in the manifest, because it uses neither the verification route nor the realm's keys.

The check calls `GET /api/v1/read_account` at `TURNZERO_CLOUD_API` with `Authorization: Bearer <token>` and compares the answer's `account.id` with `ownerAccount`. See [`read_account`](/cloud/reference/actions/read-account/) for the exact request. It does not check which application a token was minted for.

To set `ownerAccount`, read `account.id` from `read_account` through your own Turn Zero connection. The platform supplies no environment variable for that id. Put it in a [plain manifest setting](/cloud/guides/author-the-manifest/#set-a-value-that-is-not-secret), for example `"OWNER_ACCOUNT": {"value": "<your account id>"}` inside `settings`. The id is not secret. Your code reads `process.env.OWNER_ACCOUNT` and passes it as `ownerAccount` when building the client.

For `verifyOwner`, use a [token minted for this application alone](/cloud/guides/mint-a-token/). An account-scoped token also works, but reaches every application in your account. A web page never collects either token.

Never pass it `TURNZERO_CLOUD_APP_TOKEN`: `read_account` identifies that credential as belonging to the application's owning account, so every caller would pass. A route for your own script or AI tool can use this check with `OWNER_ACCOUNT`. A route for your web page checks its session's verified email address instead, as [Let only you reach an admin route](/cloud/guides/add-sign-in-to-your-app/#6-let-only-you-reach-an-admin-route) shows.

Do not invent a shared admin key or password to get around an owner check.

### Failures

A refused verdict's `refused` is one of these:

- the verification route's reasons: `session_expired`; `session_ended`, where no session matches the value or the token's key is gone; `session_revoked`, after a sign-out, a revocation, or `revoke_app_sign_in_keys`; `user_suspended`; and `session_other_realm`, a session of another realm;
- on local verification, the token check's reason, one of `malformed`, `realm_mismatch`, `key_unknown`, `key_revoked`, `signature_invalid`, and `expired`, or the router header's, such as `user_revoked`;
- `http_<status>`, where the route returns an error with no name, such as an outage's 503, and `malformed_answer`, where it returns no user.

The client caches a verdict until the earliest of `cacheSeconds`, the route's `cache_until`, and the session's expiry. It caches a named refusal for ten seconds or until `cache_until`, and never caches an `http_<status>` refusal.

The client throws only at construction: if `baseUrl` is missing, or if `realmKeys` is malformed, names a different realm from `realm`, or supplies keys with no realm. A transport rejection, such as an unreachable network, also reaches the caller. The client sets no request timeout and does not retry.

## Test with the double

The test double replaces the accounts service behind the real client. Create it with `await createAccountDouble()` from `@turnzero/account/testing`. Build the client over the double's `transport`, `realmKeys`, and `keyFetch`, or call `double.client()` for the same client. The double's `signIn(user)` returns the user's `session` and the router's `header` for it. Its `signOut`, `suspendUser`, and `revokeUser` change the session's standing. Its `headerFor(session)` gives the router's header for the session's current standing. Set `cacheSeconds: 0` where a test verifies one session twice, because the client reuses a verdict for up to a minute.

To test a route of your own, write it to take the client, and pass it `account.client()` in the test. The sample's last lines test a route that returns the user's id, with a signed-in session and with none. A test runs this sample over the double.

```js
import assert from 'node:assert/strict';
import { makeVerifyClient } from '@turnzero/account';
import { createAccountDouble } from '@turnzero/account/testing';

const account = await createAccountDouble();
const client = makeVerifyClient({
  baseUrl: account.baseUrl,
  credential: account.credential,
  realmKeys: account.realmKeys,
  transport: account.transport,
  keyFetch: account.keyFetch,
  now: account.now,
  cacheSeconds: 0,
});

const { session, header } = account.signIn({ id: 'user-1' });
const verdict = await client.verifySession(session, { sessionHeader: header });
assert.equal(verdict.user.id, 'user-1');
// After a sign-out, the router's header for the session says it ended.
account.signOut(session);
const ended = await client.verifySession(session, { sessionHeader: account.headerFor(session) });
assert.equal(ended.refused, 'session_revoked');

// Testing a route: the route takes the client, so the test hands it the double's.
async function me(request, accounts) {
  const verdict = await accounts.verifySession(request.session, { sessionHeader: request.header });
  return 'user' in verdict ? { status: 200, id: verdict.user.id } : { status: 401 };
}
const routeClient = account.client({ cacheSeconds: 0 });
const user2 = account.signIn({ id: 'user-2' });
assert.deepEqual(await me(user2, routeClient), { status: 200, id: 'user-2' });
assert.deepEqual(await me({}, routeClient), { status: 401 });
```

Run the tests with `npm test` or a bare `node --test`, not `node --test` with a folder ([Test your application locally](/cloud/guides/test-your-application-locally/#4-run-the-tests)).

A server that builds its own client with no `transport` calls the global `fetch`. Replace that global with `account.fetch` in your test, and the server's calls reach the double.

A native app's request needs nothing new. Send the `session` as `Authorization: Bearer <session>`, as [The account double and a native app's bearer](/cloud/guides/test-your-application-locally/#the-account-double-and-a-native-app-s-bearer) says. The double has no token endpoint, no refresh, and no session list.

The double's `signIn(user)` also takes the user's `addresses`. A client built without `realmKeys`, such as `account.client({ realmKeys: undefined })`, returns them as given, including an address marked `source: 'tenant'`.

The client returns the refusals listed in [Failures](#failures) as `{ refused, detail }`, and throws nothing. In a test, a refused session most often means the test signed no user in with `signIn`, used another `realm`, or passed a header that is not `header` or `headerFor(session)`. Never sign a token yourself. These refusals come from the double itself:

| Refusal | Cause | Remedy |
| --- | --- | --- |
| `authentication_required`, `not_owner` | The bearer differs from the double's `credential`, or the bearer passed to `verifyOwner` was not granted as `'owner'`. | Use `double.client()`, and pass `grantBearer('owner')` to `verifyOwner`. |
| `invalid_request`, its detail starting `The request holds a NUL character` | An accounts call's address contained a NUL character (U+0000), or its JSON body contained a NUL character or an unpaired UTF-16 surrogate. The double refuses it before it reads the credential, as the platform does. | Send the text without the character. |
| `TypeError` from `createAccountDouble` | The `credential` given is not a valid credential form. | Leave the default credential. |
| `http_503` and the other `http_` codes | `refuseNext` scripted a bare status. | Assert the code. |
| `is not a refusal the accounts service returns`, `no user <id> is signed in`, `no session exists` | A script or a state change named something the double does not have. | Use a refusal the double has, and sign the user in first. |

## Calling the verification route directly

If your backend does not use the package, it can call the verification route itself. [The verification route](/cloud/concepts/verifying-an-end-user/#the-verification-route) explains when a backend needs it. This section gives the request and the response. For a complete server that calls this route with `fetch` and no package, see [Without the Account package](/cloud/guides/add-sign-in-to-your-app/#without-the-account-package).

Send `POST /accounts/v0/verify` to the platform's origin, the value of `TURNZERO_CLOUD_API`, with these headers:

- `Authorization: Bearer ` followed by the application's platform credential, from `TURNZERO_CLOUD_APP_TOKEN`.
- `Content-Type: application/json`.
- `x-turnzero-cloud-environment`, `production` or `development`, only under a credential that belongs to no environment, such as an account-wide credential or a minted token. The body member `environment` can name it instead.

The body is a JSON object whose `session` member is the session token the request sent. That is the value of the cookie `__Host-turnzero_cloud_realm`, or the token after `Bearer ` from a native app. Under an account-wide credential, the body can also name the `application`.

```json
{ "session": "turnzero_cloud_usr_1.<payload>.<signature>" }
```

A live session returns status 200 and a JSON object with these members:

- `contract_version`: `1`.
- `user`: the end user, with `id`, the opaque identifier, `realm`, `addresses`, `routes`, and `standing`, `active`. Each address is `{ email, verified }`, and a work-account address also has `source: "tenant"`. `routes` lists the sign-in methods the user has.
- `verified_at`: when the route checked the session.
- `cache_until`: 60 seconds after the check, or the session's expiry where that comes first. Reuse the answer no later than this.
- `session_expires`: the session's expiry.

A refusal returns a JSON object with `contract_version`, `error`, and `detail`. A refusal of the session itself also has `cache_until`, ten seconds ahead: hold the refusal until then.

| Refusal | Status | Meaning |
| --- | --- | --- |
| `invalid_request` | 400 | The body has no `session`, or its value does not begin `turnzero_cloud_usr_`, or the body contains a NUL character or an unpaired surrogate. |
| `authentication_required` | 401 | No credential was presented, or it matches none. |
| `session_ended` | 401 | No session matches the value, the token fails under the realm's keys, or the user no longer exists. |
| `session_revoked` | 401 | The session was signed out or revoked, or `revoke_app_sign_in_keys` revoked the key that signed the token. |
| `session_expired` | 401 | The session is past its life. |
| `user_suspended` | 403 | The end user is suspended. |
| `session_other_realm` | 403 | The session belongs to another realm, whether it is live, signed out, or expired. |
| `end_user_credential_not_admitted` | 403 | The bearer is an end user's session. It belongs in the body. |
| `transfer_grant_not_admitted`, `secret_grant_not_admitted`, `egress_key_not_admitted` | 403 | The bearer is a transfer grant, a secret grant, or an egress key. |
| `environment_required` | 400 | A credential that belongs to no environment named none, or named a value other than `production` or `development`. |
| `environment_mismatch` | 403 | The header and the body name different environments, or one other than the platform credential's own. |
| `environment_not_created` | 409 | A credential that belongs to no environment named `development` on an application with one environment. |
| `session_other_account` | 403 | The realm belongs to another account than the credential's. |
| `token_scope_refused` | 403 | `application` names another application than the one the credential is bounded to. |
| `realm_not_declared` | 404 | The application declares no `accounts` service. |

Before an accounts call runs, the platform checks its credential. That check can return 403 `account_suspended` or `insufficient_scope`, 429 `rate_capped`, or 503 `store_unavailable`. An unexpected failure returns 500 `internal`. The [refusals page](/cloud/reference/refusals/) explains each name.
