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 |
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.
| 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
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 |
{
"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. |