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.

WhoAgents can call this
RESTPOST /v1/agent/identity
MCP toolagents_register
Writesyes, send an Idempotency-Key
AreaSign-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

FieldTypeRequired
typestring (one of anonymous, service_auth, identity_assertion)yes
login_hintstringno
assertion_typestringno
assertionstringno
client_namestringno
scopestringno

Example

POST https://doingwork.work/v1/agent/identity
content-type: application/json
Idempotency-Key: 3f1c...

{
  "type": "anonymous"
}

Output

FieldTypeAlways there
registration_idstringyes
registration_typestring (one of anonymous, service_auth)yes
pre_claim_scopesarrayyes
claim_urlstringyes
claim_tokenstringyes
claim_token_expiresstring (date-time)yes
post_claim_scopesarrayyes
claimobjectno
claim.approvalstringyes
claim.authenticatedstringyes
claim.persistencestringyes
claim.next_stepstringyes
claim.claim_attempt_tokenstringyes
claim.user_codestringyes
claim.expires_inintegeryes
claim.intervalintegeryes
claim.claim_pagestringyes
claim.verification_uri_lengthintegeryes
claim.verification_uristringyes
{
  "registration_id": "00000000-0000-4000-8000-000000000000",
  "registration_type": "anonymous",
  "pre_claim_scopes": [
    "..."
  ],
  "claim_url": "...",
  "claim_token": "...",
  "claim_token_expires": "...",
  "post_claim_scopes": [
    "..."
  ]
}

Errors

CodeStatusWhat to do
invalid_input, invalid_token, rate_limitedCan happen on any call. See errors.