---
title: Add sign-in to your app
description: Let your application's users sign in with Google, GitHub, an emailed code, or a passkey, and find out in your backend which user sent each request.
slug: /guides/add-sign-in-to-your-app
order: 14
visibility: public
redirects_from: []
---

# Add sign-in to your app

Prompt:

> Let people sign in to my app with Google, GitHub, or a code sent to their email.

Also works:

- "My backend needs to know which user sent each request."
- "Some of my users don't have Google. Let them sign in with their email address."
- "Add a sign-out button."
- "Add a page where only I can delete messages."

Add the accounts service, link to `/__account/signin`, and verify sessions in your backend. Your AI tool checks the realm's enabled methods and sign-up rules; the manifest can restrict both.

Every application supports sign-in. [Manage end users](/cloud/guides/manage-end-users/#the-limits-on-emailed-codes) lists the emailed-code guards, including 1,000 codes per realm per hour for either size. Each emailed sign-in code is a charged email recipient. Read the current email rate on the [pricing page](https://turnzero.ai/pricing), or call `read_rate_card`. There is no per-request charge for sign-ins or session verifications.

At a glance:

- **Manifest:** add `{"kind": "accounts"}` to `services`.
- **Sign-in page:** link to `/__account/signin`.
- **[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 session:** the `__Host-turnzero_cloud_realm` cookie from a browser, or `Authorization: Bearer <token>` from a native app, plus the serving router's `x-turnzero-cloud-session` header, passed as `sessionHeader`.
- **The check:** `verifySession(token, { sessionHeader })` returns `{ user }`, `{ anonymous: true }`, or `{ refused }`. [Step 3 (Tell which user sent a request)](#3-tell-which-user-sent-a-request) has the whole server.

## What your AI tool does

- Reads the `add-sign-in` [skill](/cloud/concepts/glossary/#skill) (`read_context`, id `skill:add-sign-in`) and follows it.
- Changes sign-in methods in the manifest's `realm` member where it sets them for every realm. `configure_app_sign_in` refuses changes to fields the manifest names ([Configure the realm](/cloud/guides/manage-end-users/#4-configure-the-realm)).
- Deploys the change as [Deploy from your computer](/cloud/getting-started/deploy-an-application/) describes.
- Asks you which sign-in methods to offer before it sets them, if your prompt does not say.

## What you need

- Which sign-in methods to offer: Google, GitHub, a code emailed to the person, or a passkey. A company's work accounts and Sign in with Apple have [their own guide](/cloud/guides/add-work-account-or-apple-sign-in/).

## Before your AI starts

**For the AI tool:** Check the following before starting.

- A connected, signed-in AI tool ([Connect your AI assistant](/cloud/getting-started/connect-your-tool/)).
- A deployed application with a backend, its identifier from `list_applications`, and its manifest ([Deploy from your computer](/cloud/getting-started/deploy-an-application/)).
- For session checks, use the [Account](/cloud/backend-packages/account/) package by default, installed as [Use the library](/cloud/guides/use-the-library/) describes. For a project that takes no package, use the platform's route as [Without the Account package](#without-the-account-package) shows.

## Steps

### 1. Turn on sign-in

Add `{"kind": "accounts"}` to the manifest's `services` array and submit the manifest. The application then has one end-user [realm](/cloud/concepts/glossary/#realm) for each environment. A realm is that environment's own list of users, with their sign-ins, passkeys, and invitations. Each realm is separate from other applications and from Turn Zero's own accounts, so your users need no Turn Zero account.

The default methods are `google`, `github`, `email`, and `passkey`. With a `public` audience, sign-up is open by default. Call `read_app_sign_in` for the stored configuration and read its `detail`, which explains any restrictions from the audience. Under `invited`, only invited people may sign up; `workforce` restricts sign-in to the configured company's work accounts. [Make sign-up invitation-only](/cloud/guides/make-sign-up-invitation-only/) explains invitations, and [Work-account sign-in](/cloud/guides/add-work-account-or-apple-sign-in/) explains workforce access.

A new application has one environment, production. So testers sign in there, beside your live users, even while the backend runs on your machine. If you turn on a development environment, it gets a realm of its own, which can hold at most ten users ([Manage end users](/cloud/guides/manage-end-users/#4-configure-the-realm)).

### 2. Send people to sign in

Give your pages a link to `/__account/signin`, the sign-in page, which shows the sign-in methods the realm offers. The sign-in pages are on your application's own hostnames, under `/__account/`. Your own routes cannot use that path.

- A link to `/__account/start/<method>`, such as `/__account/start/google`, starts that provider's sign-in at once, without the sign-in page. A "Continue with Google" button on your own page can link there. The method must be one the realm offers of `google`, `github`, `apple`, and `entra`, or the link returns 400 `route_not_enabled`.
- After a successful ordinary sign-in, the browser returns to `/` on the same hostname.
- To return the person elsewhere, see [Choose where sign-in returns](#choose-where-sign-in-returns).
- If a provider returns a declined or failed ordinary sign-in attempt, the browser stays on a result page on Turn Zero's hostname. It does not follow `return_to`. Open the application again and start over.
- Closing the provider's tab or window before it returns leaves sign-in unfinished. It does not redirect the browser back to the application.
- On an application with one environment, sign-in uses production's realm at `<label>.ai.host`; its development hostname returns 404 `realm_not_declared` under `/__account/`. With development on, `<label>-dev.ai.host` uses development's realm, even before its first deploy.
- With `turnzero` 0.38.0 or later, start `turnzero run --port 3000 --sign-in <hostname>` to sign in from `localhost`. Use the appropriate hostname above. Without `--sign-in`, hand the run a hosted session instead. [Test a local run](/cloud/guides/test-sign-in-with-test-end-users/#7-test-a-local-run) describes both routes and the browser limits.
- While an environment is [halted](/cloud/concepts/glossary/#halted-environment), its sign-in pages return 503 `environment_halted`.

#### Choose where sign-in returns

- To return the person to the page they came from, add `return_to` with that page's path to `/__account/signin` or `/__account/start/<method>`. The path must start with one `/` and no second. It must not start with `/__account/` or `/__router/`. It must use URL characters only, with any others percent-encoded. The path can be at most 512 characters long and contain no backslash. Any other value returns 400 `invalid_request`, so no link can send the person to another site.

For example, this link returns a successful browser sign-in to `/notes`:

```html
<a href="/__account/signin?return_to=%2Fnotes">Sign in</a>
```

`return_to` works with every browser sign-in method: a provider, an emailed code, and a passkey. A reauthentication and a native app's sign-in keep their own landings and do not follow it.

#### Separate sign-in and content pages

Use the platform's `/__account/signin` page for sign-in and keep your app's content on another path, such as `/notes`. Your app serves that content page; it does not need to build a sign-in page. [Choose where sign-in returns](#choose-where-sign-in-returns) shows a link that returns to `/notes` after a successful sign-in.

With an `invited` or `workforce` audience, keep private content outside `session_free_paths`. A page visit without a session is sent to the platform's sign-in page; other requests without a session are refused 401. That automatic redirect has no `return_to`, so sign-in returns to `/`. Make `/` open or link to your content page. [Make sign-up invitation-only](/cloud/guides/make-sign-up-invitation-only/) explains the audience check.

With a `public` audience, the platform does not gate your pages. Your backend must verify the session before returning private content or data, as [Tell which user sent a request](#3-tell-which-user-sent-a-request) describes.

### 3. Tell which user sent a request

A signed-in browser sends the cookie `__Host-turnzero_cloud_realm` with each request. A native app sends the same session token as `Authorization: Bearer <token>`. Treat the token as untrusted until the Account package's client, `makeVerifyClient`, verifies it. Also pass the client the request's `x-turnzero-cloud-session` header. The [serving router](/cloud/concepts/glossary/#serving-router) sets it on each request it forwards, to say whether the session is still valid. Its two forms, `valid` and `invalid` with a reason, are in [The router's session header](/cloud/concepts/verifying-an-end-user/#the-router-s-session-header).

On a deployed copy, a check that a request came from your own pages, such as one comparing its `Origin` header with your hostname, reads the hostname from `x-forwarded-host`. There the `Host` header names the platform's internal address, never the public hostname. A local run has no router, so it reads `Host` ([What the router sets on each request](/cloud/backend-packages/nodejs-runtime/#what-the-router-sets-on-each-request)).

This server responds to `GET /me` with the signed-in user's id, or 401 without a session. Deployed, its client is built with the realm keys and checks the token itself, giving the id alone with `addresses` empty ([The client](/cloud/backend-packages/account/#the-client)); for the user's email, use the second sample below.

```js
import { createServer } from 'node:http';
import { makeVerifyClient } from '@turnzero/account';

// A deployed copy receives all three settings. A local run has no
// TURNZERO_CLOUD_REALM_KEYS, so the client is built without keys there and
// verifies through the platform's route.
// When it checks the token itself, it gives the user's id alone, its addresses
// empty. A route that responds with the email uses the keyless client below.
const keys = process.env.TURNZERO_CLOUD_REALM_KEYS;
const accounts = makeVerifyClient({
  baseUrl: process.env.TURNZERO_CLOUD_API,
  credential: process.env.TURNZERO_CLOUD_APP_TOKEN,
  ...(keys ? { realmKeys: keys } : {}),
});

// The session token: the cookie's value from a browser, or the bearer from a native app.
function sessionOf(request) {
  const auth = request.headers.authorization ?? '';
  if (auth.startsWith('Bearer ')) return auth.slice('Bearer '.length);
  for (const part of (request.headers.cookie ?? '').split(';')) {
    // Spaces and tabs come off a pair and nothing else, so a name is read as it stands.
    let from = 0;
    let to = part.length;
    while (from < to && (part.charCodeAt(from) === 0x20 || part.charCodeAt(from) === 0x09)) from += 1;
    while (to > from && (part.charCodeAt(to - 1) === 0x20 || part.charCodeAt(to - 1) === 0x09)) to -= 1;
    const pair = part.slice(from, to);
    const at = pair.indexOf('=');
    if (at > 0 && pair.slice(0, at) === '__Host-turnzero_cloud_realm') return pair.slice(at + 1);
  }
  return null;
}

async function userIdOf(request) {
  const verdict = await accounts.verifySession(sessionOf(request), {
    sessionHeader: request.headers['x-turnzero-cloud-session'] ?? null,
  });
  return 'user' in verdict ? verdict.user.id : null;
}

createServer(async (request, response) => {
  if (request.url !== '/me') {
    response.writeHead(404).end();
    return;
  }
  const id = await userIdOf(request);
  response.writeHead(id ? 200 : 401, { 'content-type': 'application/json' });
  response.end(JSON.stringify(id ? { id } : { error: 'sign_in_required' }));
}).listen(Number(process.env.PORT ?? 8080));
```

A test runs this sample against the package's test double. `verifySession` returns `{ user }` for a signed-in user, `{ anonymous: true }` with no session, and `{ refused }` with a reason otherwise ([The client](/cloud/backend-packages/account/#the-client) lists them).

- In a deployed copy, every deploy and promote sets `TURNZERO_CLOUD_REALM_KEYS`, the realm's public keys. The client checks the token inside your process and gives the user's id alone.
- In a local run, `.env` holds no realm keys and the serving router does not run. So the same client asks the platform's [verification route](/cloud/concepts/glossary/#verification-route). On an application with one environment, the route checks a session someone opened on the production realm. It never opens a session itself. [Test a local run](/cloud/guides/test-sign-in-with-test-end-users/#7-test-a-local-run) describes browser sign-in with `run --sign-in` and handing the run a hosted session for scripts.

Where a route needs the user's verified email, build a second client without keys and call it only for that read. A route that needs both the id and the address builds that one client alone, since the verification route's `user` carries the `id` too. That client asks the verification route, which returns the user's addresses, sign-in methods, and [standing](/cloud/concepts/glossary/#standing). The verification request has no per-request charge. A test runs this sample against the double too.

```js
import { makeVerifyClient } from '@turnzero/account';

// Built without realm keys, this client asks the platform's verification
// route, which returns the user's addresses.
const route = makeVerifyClient({ baseUrl: process.env.TURNZERO_CLOUD_API, credential: process.env.TURNZERO_CLOUD_APP_TOKEN });

// session: the token the request carried, as sessionOf above reads it.
export async function verifiedEmail(session) {
  const verdict = await route.verifySession(session);
  if (!('user' in verdict)) return null;
  return verdict.user.addresses.find((address) => address.verified)?.email ?? null;
}
```

A work-account user's address counts as verified only where the company's tenant vouches for it ([Add work-account or Apple sign-in](/cloud/guides/add-work-account-or-apple-sign-in/#2-add-work-account-sign-in)). [Verifying an end user](/cloud/concepts/verifying-an-end-user/) explains the token, the keys, and the router's header.

#### Without the Account package

Use the Account package by default; if your project takes no package, call the platform's [verification route](/cloud/concepts/glossary/#verification-route) with `fetch`.

This one file responds to `GET /me` with the signed-in user's id and verified address, or 401 without a session, for a suspended user, or for a session of another realm. It answers `GET /health` for the manifest's health path. It reads `TURNZERO_CLOUD_API` and `TURNZERO_CLOUD_APP_TOKEN`, as the keyless client above does; a local run gets them from `.env`, started with `turnzero run`. A test runs this sample against the platform's route.

```js
// server.mjs: GET /me with no package, asking the platform who holds the session
import { createServer } from 'node:http';

// The session token: the cookie's value from a browser, or the bearer from a native app.
function sessionOf(request) {
  const auth = request.headers.authorization ?? '';
  if (auth.startsWith('Bearer ')) return auth.slice('Bearer '.length);
  for (const part of (request.headers.cookie ?? '').split(';')) {
    // Spaces and tabs come off a pair and nothing else, so a name is read as it stands.
    let from = 0;
    let to = part.length;
    while (from < to && (part.charCodeAt(from) === 0x20 || part.charCodeAt(from) === 0x09)) from += 1;
    while (to > from && (part.charCodeAt(to - 1) === 0x20 || part.charCodeAt(to - 1) === 0x09)) to -= 1;
    const pair = part.slice(from, to);
    const at = pair.indexOf('=');
    if (at > 0 && pair.slice(0, at) === '__Host-turnzero_cloud_realm') return pair.slice(at + 1);
  }
  return null;
}

// The signed-in user, or null for no session or a session the platform refuses.
async function userOf(request) {
  const session = sessionOf(request);
  if (!session?.startsWith('turnzero_cloud_usr_')) return null;
  const answer = await fetch(`${process.env.TURNZERO_CLOUD_API}/accounts/v0/verify`, {
    method: 'POST',
    headers: { authorization: `Bearer ${process.env.TURNZERO_CLOUD_APP_TOKEN}`, 'content-type': 'application/json' },
    body: JSON.stringify({ session }),
    signal: AbortSignal.timeout(10_000),
  });
  const body = await answer.json();
  if (answer.ok) return body.user;
  // A refusal of the session carries cache_until. Any other is no verdict on the session.
  if (body.cache_until) return null;
  throw new Error(`verification route: ${body.error}`);
}

createServer(async (request, response) => {
  if (request.url === '/health') {
    response.writeHead(200).end();
    return;
  }
  if (request.url !== '/me') {
    response.writeHead(404).end();
    return;
  }
  try {
    const user = await userOf(request);
    const email = user?.addresses.find((address) => address.verified)?.email ?? null;
    response.writeHead(user ? 200 : 401, { 'content-type': 'application/json' });
    response.end(JSON.stringify(user ? { id: user.id, email } : { error: 'sign_in_required' }));
  } catch (error) {
    console.error(error);
    response.writeHead(503, { 'content-type': 'application/json' });
    response.end(JSON.stringify({ error: 'verification_unavailable' }));
  }
}).listen(Number(process.env.PORT ?? 8080));
```

The verification request has no per-request charge, and your server may reuse an answer until its `cache_until`. [Calling the verification route directly](/cloud/backend-packages/account/#calling-the-verification-route-directly) lists the answer's members and its refusals.

#### Test the server offline

Run `server.mjs` in a test without the Account package. The test calls a local stand-in for the verification route, so it needs no connection to Turn Zero. It starts the stand-in on the computer, points `TURNZERO_CLOUD_API` at it, and answers as [Calling the verification route directly](/cloud/backend-packages/account/#calling-the-verification-route-directly) lists. Run it with `node --test test/me.test.mjs` from the folder that holds `server.mjs`.

```js
// test/me.test.mjs: GET /me with no package, offline, against a stand-in for the verification route
import { after, test } from 'node:test';
import assert from 'node:assert/strict';
import { spawn } from 'node:child_process';
import { once } from 'node:events';
import { createServer } from 'node:http';

const SESSION = 'turnzero_cloud_usr_test.session';

// The stand-in answers POST /accounts/v0/verify as the platform does: the user for SESSION, a refusal otherwise.
const route = createServer(async (request, response) => {
  let body = '';
  for await (const chunk of request) body += chunk;
  const live = JSON.parse(body).session === SESSION;
  const now = Date.now();
  response.writeHead(live ? 200 : 401, { 'content-type': 'application/json' });
  response.end(JSON.stringify(live
    ? {
        contract_version: 1,
        user: { id: 'usr_test', realm: 'realm_test', addresses: [{ email: 'ada@example.com', verified: true }], routes: ['google'], standing: 'active' },
        verified_at: new Date(now).toISOString(),
        cache_until: new Date(now + 60_000).toISOString(),
        session_expires: new Date(now + 3_600_000).toISOString(),
      }
    : { contract_version: 1, error: 'session_ended', detail: 'No session matches.', cache_until: new Date(now + 10_000).toISOString() }));
}).listen(0, '127.0.0.1');
await once(route, 'listening');

// A free port for the server, then the server with its two settings pointing at the stand-in.
const probe = createServer().listen(0, '127.0.0.1');
await once(probe, 'listening');
const port = probe.address().port;
await new Promise((resolve) => probe.close(resolve));
const server = spawn(process.execPath, ['server.mjs'], {
  env: { ...process.env, PORT: String(port), TURNZERO_CLOUD_API: `http://127.0.0.1:${route.address().port}`, TURNZERO_CLOUD_APP_TOKEN: 'test-credential' },
  stdio: 'inherit',
});
after(() => {
  server.kill();
  route.closeAllConnections();
  route.close();
});

const origin = `http://127.0.0.1:${port}`;
for (let tries = 0; ; tries += 1) {
  try {
    if ((await fetch(`${origin}/health`)).ok) break;
  } catch {}
  if (tries === 50) throw new Error('server.mjs did not start');
  await new Promise((resolve) => setTimeout(resolve, 100));
}

test('a live session answers its id and verified address', async () => {
  const answer = await fetch(`${origin}/me`, { headers: { authorization: `Bearer ${SESSION}` } });
  assert.equal(answer.status, 200);
  assert.deepEqual(await answer.json(), { id: 'usr_test', email: 'ada@example.com' });
});

test('no session, and a session the route refuses, answer 401', async () => {
  assert.equal((await fetch(`${origin}/me`)).status, 401);
  const refused = await fetch(`${origin}/me`, { headers: { authorization: 'Bearer turnzero_cloud_usr_other' } });
  assert.equal(refused.status, 401);
});
```

Add a case for each answer your server depends on, such as a suspended user's 403, from the refusals that page lists.

### 4. Show the user and sign out

`GET /__account/me` returns the signed-in user to a page as JSON. It returns 401 without a live session, and 403 `user_suspended` for a suspended user. A page that shows who is signed in can read the address here, with no backend route of your own.

| Member | What it contains |
| --- | --- |
| `user.id` | The user's opaque identifier, the same one your backend's verification returns. |
| `user.realm` | The realm the user belongs to. |
| `user.addresses` | The user's verified addresses, each as `email` and `verified`. A user who signed in only with a work account also has the tenant's address, marked `"source": "tenant"`, verified or not. |
| `user.routes` | The providers linked to the user: `google`, `github`, `apple`, `entra`, or `email`. A passkey is not listed. |
| `user.standing` | `active`. |
| `session.expires` | When the session ends. |

To sign the user out, send a POST to `/__account/signout`, for example with `fetch('/__account/signout', { method: 'POST' })` from your page. The post returns 200 with `{"signed_out": true}` and clears the session cookie. A `fetch` from your own page needs nothing more, since the browser sends the page's origin, and a post carrying the session cookie from another origin is refused 400 `invalid_request`.

A plain link works too: `<a href="/__account/signout">Sign out</a>`. The page it opens has one Sign out button, which ends the session and returns the user to your application's root. Opening the link alone signs no one out.

### 5. Offer other sign-in methods

If the manifest sets [`realm.sign_in_methods`](/cloud/guides/author-the-manifest/#configure-sign-in-and-push-in-the-manifest), change that complete list in the manifest and call `submit_manifest`. It applies to every realm the application has. A conflicting `configure_app_sign_in` call is refused `manifest_owned_field`.

Otherwise, call `configure_app_sign_in` with the application's identifier and the complete `sign_in_methods` list. It replaces the current list at once, without a redeploy. The call changes production when `environment` is omitted; make a separate call with `environment: "development"` to change development too. An empty list turns sign-in off.

| Sign-in method | How the person signs in |
| --- | --- |
| `google` | With a Google account. |
| `github` | With a GitHub account. |
| `email` | With a six-digit code emailed to their address. |
| `passkey` | With a passkey on a device or in a password manager. |
| `entra` | With one company's Microsoft work account ([Add work-account or Apple sign-in](/cloud/guides/add-work-account-or-apple-sign-in/)). |
| `apple` | With Sign in with Apple ([Add work-account or Apple sign-in](/cloud/guides/add-work-account-or-apple-sign-in/)). |

Google and GitHub sign-in run on the platform's own registrations with Google and GitHub, so you register no app with either. A passkey is a faster way to sign in for someone who uses the emailed code. So `configure_app_sign_in` accepts `passkey` only beside `email`, and refuses `passkey` alone with `passkey_not_sole_route`. [Passkeys for your users](/cloud/guides/manage-end-users/#5-passkeys-for-your-users) covers when a user is offered one.

#### The emailed code

To offer emailed codes, include `email` in the complete `sign_in_methods` list, for example `["google", "github", "email"]`. Use the manifest or `configure_app_sign_in` as [step 5 (Offer other sign-in methods)](#5-offer-other-sign-in-methods) explains. The sign-in page then shows an address form after the provider buttons. The person enters the six-digit code there, in the same browser, within ten minutes.

For a custom page, [Browser email-code sign-in](/cloud/reference/browser-email-code-sign-in/) gives the form fields, binding cookie, response formats, redirects, and error handling.

The code comes from `donotreply@turnzero.ai`, with the sender name Turn Zero. Its subject is "Your sign-in code for" followed by the [hostname label](/cloud/concepts/glossary/#hostname-label). The message is fixed text with no link. One address receives at most five codes an hour by default, and [The limits on emailed codes](/cloud/guides/manage-end-users/#the-limits-on-emailed-codes) lists every limit and which you can raise. The development realm sends real mail under the same limits.

### 6. Let only you reach an admin route

For owner moderation in a browser, such as letting only you delete a message, use your verified email address in a setting such as `OWNER_EMAIL`. An address is personal data. Your AI tool [stores and binds the value](/cloud/getting-started/store-a-secret/), so it stays out of the project's source.

Your AI tool can read `account.address` from `read_account` under your signed-in session or an authorized computer's token. Other minted tokens receive no address. Otherwise, you name the address in the conversation.

- If the address is known before the first deploy, your AI tool stores it with `store_secret`, binds `OWNER_EMAIL` in the manifest, and deploys. You can use the admin route from your first sign-in with that verified address. Invite yourself first if sign-up is invitation-only ([Invite each person](/cloud/guides/make-sign-up-invitation-only/#3-invite-each-person)).
- If the address is unknown and nobody can be asked, leave `OWNER_EMAIL` unset and omit its binding. The route refuses every admin request. Before reporting completion, your AI tool says admin access stays closed until your address is stored and bound. Once the address is known, it stores the value, adds the binding, and deploys or promotes a version that includes it.

  If the action must work before the address is known, provide a separate route for your own script or AI tool, guarded by `verifyOwner` and `OWNER_ACCOUNT`. Your AI tool reads `account.id` from `read_account`, puts it in the plain `OWNER_ACCOUNT` setting, and passes it as the Account client's `ownerAccount`. The caller sends a token minted for this application under your Turn Zero account as a bearer. Never send `TURNZERO_CLOUD_APP_TOKEN` or collect the token on a web page.

Adding a binding after deployment requires a deploy or promote. A restart reapplies the serving version's bindings; it does not pick up a new binding from the current manifest. To change an address whose binding the serving version already has, replace the stored value and call `restart_application` for that environment.

The route verifies the session as [step 3 (Tell which user sent a request)](#3-tell-which-user-sent-a-request) shows. Build its Account client without `realm` or `realmKeys`, so verification returns the user's addresses through the platform's route. There is no per-request charge for verification. Refuse 403 unless verification returns a user, `OWNER_EMAIL` is non-empty, and `verdict.user.addresses` includes an address whose `verified` is `true` and whose `email` matches it, ignoring case.

Make the route a POST or DELETE, never a GET. Also refuse 403 when the request's `Origin` does not name your own hostname, read as step 3 (Tell which user sent a request) says. Another application's page under `ai.host` counts as the same site, so its request can carry your session cookie.

Each environment's realm has its own users. Store the address separately for each environment, and sign in there with that verified address. Do not make the first person who signs in the owner.

Never ask for your Turn Zero token in a page. For your own script or AI tool, a route can use the Account package's `verifyOwner` with `OWNER_ACCOUNT`. Give it 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. Never pass `TURNZERO_CLOUD_APP_TOKEN`: the check would treat any caller as the owner. It does not check a browser's sign-in session.

Do not invent a shared admin key or password to get around an owner check. If no one else needs to sign in, set each realm's `creation` to `invited` after your first sign-in ([Make sign-up invitation-only](/cloud/guides/make-sign-up-invitation-only/)).

## Expected result

`read_app_sign_in` shows the current realm settings ([Configure the realm](/cloud/guides/manage-end-users/#4-configure-the-realm)). Fields listed in the manifest's `realm` member change when you submit the manifest. `configure_app_sign_in` changes the other fields directly, without a redeploy; its answer's `page` names this guide and its `detail` lists the changes. Deploying code alone changes no realm setting.

- With no sign-in method enabled, no one can sign in. Under the `invited` audience, sign-up stays invitation-only ([Make sign-up invitation-only](/cloud/guides/make-sign-up-invitation-only/)).
- A new `session_days` applies to sessions opened from then on. A browser session keeps its expiry, and a native app's session takes the new length at its next refresh.
- `session_cap_days` is the most days a native app's session can run from its creation, checked at each refresh.
- A declared native client holds no secret. Sign-in accepts only its declared redirect URIs, except that a declared loopback URI's port may differ ([Sign in from a native app](/cloud/guides/sign-in-from-a-native-app/)).
- Raising `minimum_version` so that it refuses versions seen in the last day adds `warnings`, which list those versions ([Keep installed clients compatible](/cloud/guides/keep-installed-clients-compatible/)).
- The `entra` or `apple` settings are saved, and that route is offered once `sign_in_methods` includes it ([Add work-account or Apple sign-in](/cloud/guides/add-work-account-or-apple-sign-in/)).

On the deployed hostname, the sign-in page shows the methods you enabled, and a person who signs in becomes a user. Your backend's `GET /me` then returns that user's id, and 401 without a session.

## Refusals

See the [refusals reference](/cloud/reference/refusals/) for other platform errors.

A refused management call changes nothing. The rows from `development_realm_full` down are the sign-in pages' answers to the person signing in.

| Refusal | Status | Cause | Remedy |
| --- | --- | --- | --- |
| `invalid_request` | 400 | A `configure_app_sign_in` member is malformed, such as an unknown sign-in method; the `detail` identifies it. Or a `return_to` path breaks the rules of step 2 (Send people to sign in). | Correct the member or the path and try again. |
| `manifest_owned_field` | 409 | `configure_app_sign_in` tried to change a field set by the manifest. | Change that field in the manifest and call `submit_manifest`. |
| `passkey_not_sole_route` | 400 | `sign_in_methods` listed `passkey` without `email`. | List `email` beside `passkey`, or leave `passkey` out. |
| `realm_not_declared` | 404 | The manifest declares no accounts service. On one environment, the development hostname returns it under `/__account/` too. | Add `{"kind": "accounts"}` to `services` and submit the manifest. On one environment, sign in at the production hostname. |
| `environment_not_created` | 409 | A call named `development` on an application with one environment. | Leave `environment` out, or turn development on with `create_environment`. |
| `development_realm_full` | 403 | A sign-in would create an eleventh user in a development realm. | Delete a development user with `delete_end_user` and `environment: "development"`. |
| `route_not_enabled` | 400 | A `/__account/start/<method>` link named a method other than `google`, `github`, `apple`, or `entra`, or one of them that the realm does not offer. | Add that provider to `sign_in_methods`. For an emailed code or a passkey, link the sign-in page. |
| `user_suspended` | 403 | A suspended user signed in, or read `GET /__account/me`. | Restore the user by calling `set_end_user_standing` with `standing: active`. |
| `signin_rate_limited` | 429 | One network address started more sign-ins in an hour than the realm allows, or more than its share of emailed-code starts across the platform. | Wait for the hour to pass, or raise `limits.signin_starts_per_hour` ([The limits on emailed codes](/cloud/guides/manage-end-users/#the-limits-on-emailed-codes)). |
| `signin_code_rate_limited` | 429 | An emailed-code start passed one of the limits on codes. | Wait for the hour to pass. Only `limits.code_sends_per_hour` can be raised. |
| `email_domain_undeliverable` | 400 | An emailed-code start was for an address whose domain publishes no mail server, so no code could reach it. A reauthentication, which sends to the verified address, is refused the same way. | The person corrects a typo in the address and starts again. Where the start posted no address, they sign in with another route. |

## Related

- [Build an app with sign-in and AI](/cloud/guides/build-an-app-with-sign-in-and-ai/) follows one complete app from sign-in to an AI answer.
- [Make sign-up invitation-only](/cloud/guides/make-sign-up-invitation-only/) limits sign-up to invited people, and runs a private beta behind a notice page.
- [Add work-account or Apple sign-in](/cloud/guides/add-work-account-or-apple-sign-in/) adds a company's work accounts or Sign in with Apple.
- [Manage end users](/cloud/guides/manage-end-users/) invites, lists, suspends, and deletes users, and lists every realm setting.
- [Account](/cloud/backend-packages/account/) is the reference for the verification client, and [Verifying an end user](/cloud/concepts/verifying-an-end-user/) explains the token it checks.
- [Sign in from a native app](/cloud/guides/sign-in-from-a-native-app/) signs in the users of a mobile or desktop app through the same realm.
- [Test sign-in with test end users](/cloud/guides/test-sign-in-with-test-end-users/) tests the signed-in paths with no person signing in. A tool with no shell passes a test end user to `request_route` as `test_end_user`, and the platform signs it in for that call.
- [configure_app_sign_in](/cloud/reference/actions/configure-app-sign-in/) in the generated reference gives the action's arguments, result, and refusals.
- The turnzero command's [notes-app template](/cloud/concepts/turnzero-command/#the-notes-app-template) and [ai-chat template](/cloud/concepts/turnzero-command/#the-ai-chat-template) write apps with sign-in and sign-out links, and a server that reads the signed-in user as step 3 (Tell which user sent a request) shows. Choose notes-app for private database records, or ai-chat for an AI conversation.
