---
title: "Register an agent identity"
method: POST
path: "/agent/identity"
tags: ["Agent Discovery"]
---

# Register an agent identity

`POST /agent/identity`

## Request

- Base URL: `https://xquik.com`
- URL: `https://xquik.com/agent/identity`
- Auth: none required

Register an agent for a user's verified email. The user claims it at claim.verification_uri with claim.user_code. Poll the token endpoint with claim_token until then. Keep every token secret.

## Request body

- AgentIdentityRequest: A service_auth registration for a user's verified email.
  - `type` 'service_auth', required
  - `login_hint` string, email, required: The user's verified email. The user must sign in with it to claim the agent.

## Response `200`

The registration & the code the user enters to claim it.

- AgentIdentityRegistration: A pending agent registration.
  - `claim` AgentClaimChallenge, required: The code the user enters to claim the agent.
    - `expires_in` 600, required: Seconds until the user code expires.
    - `interval` 5, required: Seconds to wait between token polls.
    - `user_code` string, required: The 6-digit code the user enters.
    - `verification_uri` string, uri, required: The page where the user signs in & enters the code.
  - `claim_token` string, required: Poll the token endpoint with it & refresh the user code with it. Keep it secret.
  - `claim_token_expires` string, date-time, required: When claim_token expires, 24 hours after registration.
  - `claim_url` string, uri, required: Where to refresh an expired user code.
  - `post_claim_scopes` string[], required: The scopes the access token gets once claimed.
  - `registration_id` string, required
  - `registration_type` 'service_auth', required

## Other responses

- `400`: The body isn't JSON, isn't a service_auth request or has an invalid login_hint.
- `413`: The request body exceeds 4 KiB.
- `415`: The body isn't application/json.
- `429`: Too many registrations. Retry after Retry-After.
- `500`: Unexpected error.
- `default`: Unexpected error.

## Changes

- **2026-11-02** `20d4bcaa8f4e`: 2 breaking, 1 info
  - the `claim/expires_in` response's property format changed from `int64` to no format for status `200`
  - the `claim/interval` response's property format changed from `int64` to no format for status `200`
  - removed the non-success response with the status `500`
- **2026-11-02** `48f2012c62b3`: 1 info
  - added the non-success response with the status `500`
- **2026-11-01** `1863d7ef8b4d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/xquik-dev/apis/xquik-api/changes/agent/identity/post.md)

---

[API](https://skmtc.dev/xquik-dev/apis/xquik-api.md) - [All operations](https://skmtc.dev/xquik-dev/apis/xquik-api/llms.txt) - [OpenAPI document](https://skmtc.dev/xquik-dev/apis/xquik-api/revisions/db6708e077dc?raw)