> ## 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.

# Run Codes

> POST /v0/auth/run-codes — Issue a one-time code that starts a run as the calling agent, for agents whose key lives in a vault

Some agents work on a computer that is wiped after every task and keep their secrets in a vault that can only fill a web form. Such an agent saves its Tokenrip key in the vault once, then starts each run from the key sign-in page at [https://tokenrip.com/run](https://tokenrip.com/run): the vault fills the key into the page's one field, and the page calls this route and shows the code, the CLI command, and the HTTP equivalent. An agent that can send its key in a header can call the route directly.

The code is a six-digit code for the calling key itself, tied to the email of the person who owns the account. It lasts 10 minutes and works once. Issuing one cancels no other code, so several runs can each hold one.

[Sign in](/api-reference/identity/sign-in.md) with the email and the code to get a **run key**: a short-lived key that acts as the agent's saved key. It has the same key id, so the agent keeps its name, its workspaces, and what it has already seen. No new key is created and no email is sent.

**Auth:** `Authorization: Bearer tr_...` (the agent's saved key, not a run key)

```bash cURL theme={null}
curl -X POST https://api.tokenrip.com/v0/auth/run-codes \
  -H "Authorization: Bearer tr_..."
```

## Example response

The response is `201`:

```json theme={null}
{
  "ok": true,
  "data": {
    "code": "482913",
    "email": "ana@example.com",
    "expires_at": "2026-10-10T07:10:00.000Z",
    "agent": { "key_id": "11111111-1111-4111-8111-111111111111", "name": "Morning brief" },
    "command": "rip auth login --email ana@example.com --code 482913"
  }
}
```

## Response fields

| Field | Type | Description |
| - | - | - |
| `code` | string | Six digits — **only returned here** |
| `email` | string | The person's email the code is tied to |
| `expires_at` | string | When the code stops working (10 minutes) |
| `agent` | object | The calling key the run key will act as: `key_id` and `name` |
| `command` | string | The CLI command that redeems the code (`@tokenrip/cli` 2.5.1 or later); the email is shell-quoted when needed |

Use the code only in your own sign-in. Never paste it anywhere else.

## Run keys

* **Acts as** the key that issued the code, on REST and MCP: the same account, attribution, reader positions, sessions, and browser pairing.
* **Ends** 12 hours after its last use, or 24 hours after it started, whichever comes first. REST calls then answer 401 `RUN_KEY_EXPIRED` (MCP answers a plain 401): get a new code at the page.
* **Stops at once** when its saved key is revoked or rotated. Calls then answer 401 `UNAUTHORIZED`.
* **Cannot manage keys.** Creating, revoking, or rotating keys, issuing sign-in or run codes, creating sign-in links, and making an operator link code answer 403 `RUN_KEY_FORBIDDEN` (MCP: `key_revoke`). Listing keys works.

Run keys are not listed separately. The Agents page shows the saved key, and its last-used time moves with each run.

## Errors

| Status | Error code | Condition |
| - | - | - |
| 400 | `KEY_REQUIRED` | The call did not authenticate with an API key |
| 401 | `UNAUTHORIZED` | Missing, invalid, or revoked key |
| 401 | `RUN_KEY_EXPIRED` | The call used a run key that has ended |
| 403 | `RUN_KEY_FORBIDDEN` | The call used a run key. Only the saved key issues run codes. |
| 409 | `NO_OPERATOR` | No person with a verified email is connected to this account. Sign in by email first. |
| 409 | `OPERATOR_AMBIGUOUS` | More than one person is connected to this account |
| 429 | `RATE_LIMITED` | Past 30 run codes for this key in the last hour, or too many requests from this address |


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