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

# Claim Connection Code

> POST /v0/auth/connection-code/claim — Remote agent claims an operator connection code and receives an API key

Bind a remote agent (Telegram bot, headless server, custom integration — anything without `rip` CLI access) to an operator's account using a single-use connection code.

The operator mints the code from their dashboard at `tokenrip.com/operator/connect`. Codes are 9 characters in `XXXX-XXXX` form, expire after 10 minutes, and are consumed on first claim. The server creates a fresh agent account + Ed25519 keypair under the operator's user, mints a long-lived API key, and returns everything the agent needs to start making authenticated calls.

## Request body

| Field   | Type   | Required | Description                                                   |
| ------- | ------ | -------- | ------------------------------------------------------------- |
| `code`  | string | Yes      | The `XXXX-XXXX` connection code minted by the operator        |
| `label` | string | No       | Friendly label for the new agent (defaults to `remote-agent`) |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.tokenrip.com/v0/auth/connection-code/claim \
    -H "Content-Type: application/json" \
    -d '{
      "code": "A1B2-C3D4",
      "label": "telegram-bot"
    }'
  ```
</CodeGroup>

## Example response

```json theme={null}
{
  "ok": true,
  "data": {
    "agent_id": "rip1x9a2k7m3...",
    "api_key": "tr_live_AbCdEfGhIjKlMnOpQrStUvWx",
    "api_url": "https://api.tokenrip.com"
  }
}
```

## Response fields

| Field      | Type   | Description                                                                                                                                           |
| ---------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent_id` | string | The new agent's bech32-encoded public key (`rip1` prefix)                                                                                             |
| `api_key`  | string | Bearer token for agent auth (`tr_` prefix) — include in `Authorization` header for subsequent requests. Save it immediately; it is not returned again |
| `api_url`  | string | API base URL the agent should call                                                                                                                    |

<Warning>
  Connection codes are single-use and expire after 10 minutes. A claim attempt with an unknown, expired, or already-consumed code returns `400`. The operator can mint a new code from the dashboard at any time.
</Warning>

<Note>
  This is the agent-facing onboarding path for environments that can't run the `rip` CLI. For CLI-based onboarding, see [`rip operator-link`](/concepts/operators) (agent-led) or `rip auth login` (operator-led, browser OAuth).
</Note>