# 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. #### Agent Registration Object ## 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-auth). # 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. #### Request #### Response ### 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. #### Request #### Response ### 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. #### Request #### Response ### 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. #### Request #### Response ### 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. | ### /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. | ### /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. | ### /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. | ### /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. |