Register an AI agent

auth.md Step 3. service_auth: an AI agent registers for the account login_hint names; show the person claim.verification_uri and claim.user_code (only that account, signed in with a verified email, can approve it), then poll the token endpoint with the claim grant. identity_assertion: an ID-JAG from a trusted agent provider (issuer_not_enabled while none is); it never creates or verifies an account. The first ID-JAG of a provider subject answers 401 interaction_required with a claim ceremony; once the person confirmed the link, an ID-JAG answers an identity assertion valid for at most an hour. 401 login_required when auth_time is missing or over an hour old. Refusals carry detail.reason. anonymous answers anonymous_not_enabled. 10 registrations per address per minute; 30 ID-JAGs per provider subject per 10 minutes.

POST /agent/identity

Register an AI agent

cURL

curl --request POST \
  --url https://dev.simforge.ai/agent/identity \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "service_auth",
  "login_hint": "<string>",
  "scope": "<string>"
}
'

200

{
  "registration_id": "<string>",
  "registration_type": "service_auth",
  "claim_url": "<string>",
  "claim_token": "<string>",
  "claim_token_expires": "<string>",
  "post_claim_scopes": [
    "<string>"
  ],
  "claim": {
    "user_code": "<string>",
    "expires_in": 123,
    "verification_uri": "<string>",
    "interval": 123
  }
}

Body

application/json

Option 1

Option 2

type · enum<string> · required

Available options: service_auth

login_hint · string · required

The email of the SimForge account the agent acts for. Only that account, signed in and with a verified email, can approve the registration.

Required string length: 3 - 320

scope · string

Space-separated scopes the person is asked to approve. Omitted: every scope in the metadata's scopes_supported.

Maximum string length: 200

Response

200

application/json

A service_auth registration and its first user code, or an identity assertion for a linked provider subject.

Option 1

Option 2

registration_id · string · required

registration_type · enum<string> · required

Available options: service_auth, identity_assertion

claim_url · string · required

Where to re-mint a user code for this registration (POST, with claim_token and the same email).

claim_token · string · required

Returned once: poll the token endpoint with it. Keep it in memory only.

claim_token_expires · string · required

When the registration closes (ISO 8601); after it, register again.

post_claim_scopes · string[] · required

claim · object · required

Show child attributes