---
title: "Register an agent (Auth.md)"
method: POST
path: "/agent/identity"
tags: ["agent-auth"]
---

# Register an agent (Auth.md)

`POST /agent/identity`

## Request

- Base URL: `https://api.letsship.ai/v1`
- URL: `https://api.letsship.ai/v1/agent/identity`
- Auth: none declared

An agent registers itself: anonymous (no user yet), service_auth (the user's email, confirmed by the user on the console) or identity_assertion (an ID-JAG from a trusted provider). Returns a service-signed identity_assertion or a claim ceremony, never a credential. Read https://letsship.ai/auth.md for the whole flow.

## Request body

- union
  - object
    - `type` 'anonymous', required
    - `agent_name` string: What the agent calls itself. Shown on the claim page as the agent's own words; the person names the delegation.
  - object
    - `type` 'service_auth', required
    - `login_hint` string, required
    - `agent_name` string: What the agent calls itself. Shown on the claim page as the agent's own words; the person names the delegation.
  - object
    - `type` 'identity_assertion', required
    - `assertion_type` string, required: urn:ietf:params:oauth:token-type:id-jag. The auth.md v0.1 value verified_email (with the email as the assertion) is accepted as service_auth.
    - `assertion` string, required
    - `agent_name` string: What the agent calls itself. Shown on the claim page as the agent's own words; the person names the delegation.

## Response `200`

Registered.

- AgentRegistrationResponse
  - `registration_id` string, required
  - `registration_type` 'anonymous' | 'service_auth' | 'identity_assertion', required
  - `identity_assertion` string
  - `assertion_expires` string
  - `pre_claim_scopes` string[]
  - `scopes` string[]
  - `claim_url` string
  - `claim_token` string: Returned once. Keep it in memory for the claim, never longer.
  - `claim_token_expires` string
  - `post_claim_scopes` string[]
  - `claim` ClaimCeremony
    - `user_code` string, required
    - `verification_uri` string, required
    - `expires_in` integer, required
    - `interval` integer, required

## Other responses

- `400`: Invalid request, untrusted provider or a token that did not verify.
- `401`: interaction_required (claim ceremony) or login_required (stale provider login).
- `429`: Too many registrations from this address.
- `503`: The provider's signing keys could not be read. Try again.

---

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