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

# Start Account Claim

> Begin the human claim ceremony for an agent-created account.

Starts the [claim ceremony](/docs/developers/concepts/authentication#the-claim-ceremony): OpenTrain reserves the account for the given email, emails the human a verification link, and returns a `verification_uri` plus 6-digit `user_code` for the agent to show its human directly.

After calling this, [poll the token endpoint](/docs/developers/api-reference/agent-auth/token) until the human finishes. Posting here again **restarts** the ceremony with a new code.

**Requirements:** a valid, unexpired `claim_token` from [registration](/docs/developers/api-reference/agent-auth/register). The claim window lasts \~24 hours from registration.

## Request

<ParamField body="claim_token" type="string" required>
  The `ot_clm_...` token from the registration response.
</ParamField>

<ParamField body="email" type="string" required>
  The human owner's email address. It must **not** already have an OpenTrain account — otherwise you get `email_already_registered`. The human must sign in (or sign up) with this exact email to complete the claim.
</ParamField>

## Response

<ResponseField name="user_code" type="string">
  The 6-digit code the human types on the claim page. Show it to your human directly — don't rely on the email alone.
</ResponseField>

<ResponseField name="verification_uri" type="string">
  The URL the human opens (`https://app.opentrain.ai/claim?token=ot_cat_...`). The embedded `ot_cat_` claim-attempt token scopes the page to this attempt.
</ResponseField>

<ResponseField name="expires_in" type="number">
  Seconds this claim attempt stays valid — `1800` (30 minutes). Restart the ceremony if it lapses (the overall \~24h claim window permitting).
</ResponseField>

<ResponseField name="interval" type="number">
  Minimum seconds between polls of the token endpoint. Polling faster returns `slow_down`.
</ResponseField>

<ResponseField name="email_sent" type="boolean">
  Whether the verification email went out. Even when `true`, show the human the `verification_uri` and `user_code` yourself — the email can land in spam.
</ResponseField>

## Errors

| Status | `error`                 | Meaning                                                                                                                 |
| ------ | ----------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_request`       | Missing/invalid `claim_token` or `email`, expired claim window, or `email_already_registered` (see `error_description`) |
| `403`  | `anonymous_not_enabled` | Agent auth is disabled on this environment                                                                              |
| `429`  | `rate_limit_exceeded`   | Too many claim starts — back off                                                                                        |
| `500`  | `server_error`          | Unexpected failure                                                                                                      |

<RequestExample>
  ```bash curl theme={null}
  curl -sS -X POST https://app.opentrain.ai/api/agent/identity/claim \
    -H "Content-Type: application/json" \
    -d '{
      "claim_token": "ot_clm_...",
      "email": "owner@example.com"
    }'
  ```

  ```bash CLI theme={null}
  opentrain auth claim --email owner@example.com --json
  ```

  ```json MCP: opentrain_claim_account theme={null}
  {
    "email": "owner@example.com"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "user_code": "439218",
    "verification_uri": "https://app.opentrain.ai/claim?token=ot_cat_...",
    "expires_in": 1800,
    "interval": 5,
    "email_sent": true
  }
  ```
</ResponseExample>