<!-- llms.txt: https://workos.com/llms.txt -->

# Agent Registration

Agent Registration enables AI agents and programmatic clients to obtain identity credentials from an AuthKit-powered service. The registration flow issues a signed identity assertion that can be exchanged at the token endpoint for an access token or API key.

:::code-group{title="Agent Registration Object"}

```json language="json"
{
  "id": "agent_reg_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
  "type": "anonymous",
  "identity": {
    "assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZ2VudF9yZWdfMDFKOVEyWjNYNFk1VzZWN1U4VDlTMFIxUSIsImlzcyI6Imh0dHBzOi8vYXV0aGtpdC5leGFtcGxlLmNvbSIsImV4cCI6MTcxNjIzOTAyMn0.signature",
    "expires_at": "2025-01-15T12:00:00Z"
  },
  "claim": {
    "token": "clm_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
    "expires_at": "2025-01-15T13:00:00Z",
    "url": "https://authkit_domain/claim"
  },
  "scopes": {
    "pre_claim": ["read:public"],
    "post_claim": ["read:public", "write:data"]
  }
}
```

:::

## Registration types

- **`anonymous`** — No user identity. Receives limited scopes immediately and can optionally bind to a user via the claim ceremony.
- **`service_auth`** — Requires the user's email. A claim ceremony is mandatory before trusted scopes are granted.
- **`refresh`** — Rotates an expiring identity assertion using a refresh token from a previous registration.

Read more about [Agent Registration here](https://workos.com/docs/authkit/agent-registration).

# Complete a claim

## Complete a claim

Completes the claim ceremony by submitting the `user_code` that the user read from the claim page. The agent provides the `claim_token` from its original registration response alongside the code relayed by the user.

On success, the verified identity is delivered exactly once in the response — the agent must persist it immediately.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://authkit_domain/agent/identity/claim/complete" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "claim_token": "clm_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
        "user_code": "BCDF-GHJK"
    }
BODY
```

```json language="json" title="Response" tab="2"
{
  "id": "agent_reg_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
  "status": "claimed",
  "identity": {
    "assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZ2VudF9yZWdfMDFKOVEyWjNYNFk1VzZWN1U4VDlTMFIxUSIsImlzcyI6Imh0dHBzOi8vYXV0aGtpdC5leGFtcGxlLmNvbSIsImV4cCI6MTcxNjIzOTAyMn0.signature",
    "expires_at": "2025-01-15T12:00:00Z",
    "refresh_token": {
      "value": "rt_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
      "expires_at": "2025-02-15T12:00:00Z"
    }
  }
}
```

:::

### Error responses

- **`invalid_user_code`** — The user code is incorrect. Ask the user to re-read the code.
- **`user_code_expired`** — The user code has expired. Start a new claim attempt.
- **`claim_not_confirmed`** — The user has not yet signed in and viewed the code. Wait and retry.
- **`claim_expired`** — The claim has expired. Restart registration.
- **`claim_revoked`** — The claim was revoked. Restart registration.
- **`already_claimed`** — The registration has already been claimed. Restart registration.

# View a claim

## View a claim

Retrieves claim details for the authenticated claim page. This endpoint requires a valid user access token in the `Authorization: Bearer` header and reveals the `user_code` that the user reads back to the agent.

The `token` parameter is the attempt token embedded in the `verification_uri` from the claim attempt response.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://authkit_domain/agent/identity/claim/view" \
  --header "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.example" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "token": "att_01J9Q2Z3X4Y5W6V7U8T9S0R1Q"
    }
BODY
```

```json language="json" title="Response" tab="2"
{
  "id": "agent_reg_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
  "status": "pending_confirmation",
  "user_code": "BCDF-GHJK"
}
```

:::

### Error responses

- **`invalid_token`** — The attempt token is expired or invalid.
- **`unauthorized`** — The request is not authenticated with a valid user access token.
- **`email_mismatch`** — The signed-in user's email does not match the registration's login hint.

# Start a claim

## Start a claim

Starts a claim ceremony by minting a claim attempt. The response includes a `verification_uri` that the agent presents to the user. The user signs in at that URL, and the claim page reveals a `user_code` for them to relay back to the agent.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://authkit_domain/agent/identity/claim" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "type": "service_auth",
        "claim_token": "clm_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
        "login_hint": "user@example.com"
    }
BODY
```

```json language="json" title="Response" tab="2"
{
  "id": "agent_reg_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
  "type": "service_auth",
  "attempt": {
    "verification_uri": "https://authkit_domain/claim?token=att_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
    "expires_at": "2025-01-15T12:30:00Z"
  }
}
```

:::

### Error responses

- **`invalid_claim_token`** — The claim token is expired, revoked, or invalid. Restart registration.
- **`invalid_login_hint`** — The email address is invalid or does not match the registration.

# Register an agent

## Register an agent

Registers an agent identity using one of the supported identity types. The request body is a discriminated union — the `type` field determines which additional fields are required.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://authkit_domain/agent/identity" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "type": "service_auth",
        "login_hint": "user@example.com"
    }
BODY
```

```json language="json" title="Response" tab="2"
{
  "id": "agent_reg_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
  "type": "service_auth",
  "scopes": {
    "post_claim": ["read:public", "write:data"]
  },
  "claim": {
    "token": "clm_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
    "expires_at": "2025-01-15T12:30:00Z",
    "url": "https://authkit_domain/claim",
    "attempt": {
      "verification_uri": "https://authkit_domain/claim?token=att_01J9Q2Z3X4Y5W6V7U8T9S0R1Q",
      "expires_at": "2025-01-15T12:30:00Z"
    }
  }
}
```

:::

### Registration types

- **`anonymous`** — No additional fields required. Returns an identity assertion immediately along with a claim token for an optional claim ceremony.
- **`service_auth`** — Requires `login_hint`. Returns a claim token for a mandatory claim ceremony. The identity assertion is delivered after claim completion.
- **`refresh`** — Requires `refresh_token`. Returns a fresh identity assertion with a rotated refresh token.

### Error responses

- **`invalid_request`** — The request body is malformed or missing required fields for the specified type.
- **`invalid_login_hint`** — The `login_hint` email is invalid or not recognized.
- **`invalid_refresh_token`** — The refresh token is expired, revoked, or invalid.

### agent_registration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | The unique identifier for the registration. |
| `type` | string | Yes | The registration type: `anonymous`, `service_auth`, or `refresh`. |
| `identity` | object | No | The agent's signed identity, containing an assertion JWT and expiration. |
| `claim` | object | No | The claim object for registrations that support a claim ceremony. |
| `scopes` | object | No | The scopes available to the agent at each trust level. |

### POST /agent/identity/claim/complete

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `claim_token` | string | Yes | The claim token from the agent's original registration response. |
| `user_code` | string | Yes | The short code the user read from the claim page and relayed to the agent. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `claim_complete` | object | The completed claim response with the verified identity. |

### POST /agent/identity/claim/view

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | Yes | The attempt token carried in the verification URI. Extracted from the URL query parameter. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `claim_view` | object | The claim view response. |

### POST /agent/identity/claim

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | Yes | The claim method type. The `service_auth` method is a browser claim flow that can be used to claim anonymous registrations and complete service_auth registrations. |
| `claim_token` | string | Yes | The claim token from the agent's registration response. |
| `login_hint` | string | Yes | The user's email address for the claim ceremony. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `claim_attempt` | object | The claim attempt object. |

### POST /agent/identity

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | Yes | The registration type. One of `anonymous`, `service_auth`, or `refresh`. |
| `login_hint` | string | No | The user's email address. Required for `service_auth` registrations. |
| `refresh_token` | string | No | The refresh token from a previous registration. Required for `refresh` registrations. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `agent_registration` | object | The agent registration object. Shape varies by registration type. |