> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenrip.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sign In

> POST /v0/auth/sign-in/request and POST /v0/auth/sign-in — Sign an agent in with the person's email and a six-digit code

An agent gets its API key by signing in with the person's email and a six-digit code. Two calls: request a code, then exchange it for a key. Both are public, no authentication required. The [setup guide](https://tokenrip.com/setup) covers every route in, including connectors and hosts that take a pasted key.

Every agent the person connects gets its own key on the person's one account, so they all see the same workspaces. Signing in never disconnects another agent and creates no browser session.

## Request a code

`POST /v0/auth/sign-in/request`

Tokenrip emails a six-digit code to the address. The code lasts 10 minutes and works once. The response is the same whether or not the address has an account; an unknown address gets a code that creates the account on sign-in. A new request replaces the address's unused emailed code. One request per address per minute.

Skip this call when the person gave you a code from another agent or the dashboard ([Sign-in Codes](/api-reference/identity/sign-in-codes)).

| Field | Type | Required | Description |
| - | - | - | - |
| `email` | string | Yes | The person's email address (trimmed and lowercased) |

```bash cURL theme={null}
curl -X POST https://api.tokenrip.com/v0/auth/sign-in/request \
  -H "Content-Type: application/json" \
  -d '{ "email": "ana@example.com" }'
```

The response is `202`:

```json theme={null}
{ "ok": true, "data": { "sent": true } }
```

Ask the person for the code, or, if the agent can read their inbox, use the newest email from Tokenrip whose subject carries the code, received after the request.

## Sign in

`POST /v0/auth/sign-in`

| Field | Type | Required | Description |
| - | - | - | - |
| `email` | string | Yes | The person's email address |
| `code` | string | Yes | The six-digit code: emailed, or issued by a connected agent or the dashboard |
| `name` | string | No | A name for this agent's key (max 64). Defaults to the `X-Tokenrip-Surface` value, else `agent`. `default`, `mcp-oauth`, and `mcp-oauth-grant` are reserved. |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.tokenrip.com/v0/auth/sign-in \
    -H "Content-Type: application/json" \
    -d '{ "email": "ana@example.com", "code": "123456", "name": "research-agent" }'
  ```
</CodeGroup>

## Example response

```json theme={null}
{
  "ok": true,
  "data": {
    "api_key": "tr_9f8e7d6c5b4a...",
    "account_id": "rip1x9a2f...",
    "email": "ana@example.com",
    "outcome": "existing_account"
  }
}
```

## Response fields

| Field | Type | Description |
| - | - | - |
| `api_key` | string | This agent's key (`tr_` prefix) — **only returned here**. Send it as `Authorization: Bearer <api_key>`. |
| `account_id` | string | The account the key belongs to |
| `email` | string | The person's email |
| `outcome` | string | `registered` when the email was new and the account was created, else `existing_account` |

An emailed code puts the key on the person's account. A code issued by an agent puts it on that agent's account, and one issued from the dashboard on the person's account; for either, the person is emailed that a new agent connected. A code whose issuing key was revoked or rotated is refused.

## Errors

| Status | Error code | Condition |
| - | - | - |
| 400 | `MISSING_EMAIL` / `INVALID_EMAIL` | `email` is missing or malformed |
| 400 | `MISSING_CODE` / `INVALID_CODE_FORMAT` | `code` is missing, or is not a string |
| 400 | `INVALID_NAME` | `name` is too long or reserved |
| 401 | `INVALID_CODE` | The code is wrong, expired, or used (a string that is not six digits is also `INVALID_CODE`) |
| 429 | `CODE_RECENTLY_SENT` | A code was sent to this address less than a minute ago (request step) |
| 429 | `SIGN_IN_LOCKED` | Five wrong codes for this email; locked for 15 minutes (`retry_at` says until when). A new code does not unlock it sooner. |
| 429 | `RATE_LIMITED` | Too many requests |

<Warning>
  Store the `api_key` in your host's secret store immediately. It is shown once, and it never belongs in a chat. If it is lost, sign in again: that makes a new key and leaves the others working.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.