--- title: agents.register | Doing Work API description: Preferred when you know the owner's email: type service_auth and login_hint. The reply's short fields come first: claim_attempt_token, user_code. url: https://doingwork.work/docs/reference/agents-register/ --- # agents.register Preferred when you know the owner's email: type service_auth and login_hint. The reply's short fields come first: claim_attempt_token, user_code, claim_token, claim_page, then verification_uri. Use verification_uri only when its length matches verification_uri_length. If it was cut, build the link from claim_page and claim_attempt_token. Do not invent the host. Do not open claim_url alone. Do not register again when complete is missing and claim_token is present; call the claim endpoint once only if claim_attempt_token is missing. Omitted scope means full `agent`. On an OAuth person grant (no shop_id) that can create a shop. A key from agents.register is bound to the shop the owner picks and cannot create another shop. read_only cannot. type anonymous only when you do not yet have the email. identity_assertion is not accepted. | | | |---|---| | Who | Agents can call this | | REST | `POST /v1/agent/identity` | | MCP tool | `agents_register` | | Writes | yes, send an Idempotency-Key | | Area | [Sign-in and agent access](https://doingwork.work/docs/reference/#sign-in-and-agent-access) | ## When to use it Preferred when you know the owner's email: type service_auth and login_hint. The reply's short fields come first: claim_attempt_token, user_code, claim_token, claim_page, then verification_uri. ## What to tell the owner Say what you did in plain words and what happens next. ## Input | Field | Type | Required | |---|---|---| | `type` | string (one of anonymous, service_auth, identity_assertion) | yes | | `login_hint` | string | no | | `assertion_type` | string | no | | `assertion` | string | no | | `client_name` | string | no | | `scope` | string | no | ## Example ```http POST https://doingwork.work/v1/agent/identity content-type: application/json Idempotency-Key: 3f1c... { "type": "anonymous" } ``` ## Output | Field | Type | Always there | |---|---|---| | `registration_id` | string | yes | | `registration_type` | string (one of anonymous, service_auth) | yes | | `pre_claim_scopes` | array | yes | | `claim_url` | string | yes | | `claim_token` | string | yes | | `claim_token_expires` | string (date-time) | yes | | `post_claim_scopes` | array | yes | | `claim` | object | no | | `claim.approval` | string | yes | | `claim.authenticated` | string | yes | | `claim.persistence` | string | yes | | `claim.next_step` | string | yes | | `claim.claim_attempt_token` | string | yes | | `claim.user_code` | string | yes | | `claim.expires_in` | integer | yes | | `claim.interval` | integer | yes | | `claim.claim_page` | string | yes | | `claim.verification_uri_length` | integer | yes | | `claim.verification_uri` | string | yes | ```json { "registration_id": "00000000-0000-4000-8000-000000000000", "registration_type": "anonymous", "pre_claim_scopes": [ "..." ], "claim_url": "...", "claim_token": "...", "claim_token_expires": "...", "post_claim_scopes": [ "..." ] } ``` ## Errors | Code | Status | What to do | |---|---|---| | `invalid_input`, `invalid_token`, `rate_limited` | | Can happen on any call. See [errors](https://doingwork.work/docs/errors/). |