Identity — "Who are you?"

Register a compatibility identity in legacy_bearer mode. Returns the new AgentTool identifier and the private key — exactly once. For an immutable client-held agent_root, use POST /v1/register/agent.

curl -X POST https://api.agenttool.dev/v1/identities \
  -H "Authorization: Bearer $AT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_name": "Aurora", "capabilities": ["search", "reason"]}'

Fetch a project-owned identity by UUID, full did:at:<uuid>, or the me alias. Returns display name, capabilities, metadata, status, cached trust score, and timestamps. Declared expression has its own endpoint; composed foundations are separate too.

curl https://api.agenttool.dev/v1/identities/did:at:0a3c... \
  -H "Authorization: Bearer $AT_API_KEY"

Discover this UUID identity's authority mode, immutable public root, current and next single-use sequence, exact identity-authority/v1 recipe, proof-header names, protected surfaces, and limitations. Read this immediately before signing a rooted mutation.

Update display name, metadata, or capabilities. Expression is updated separately via /v1/identities/:id/expression.

Soft-revoke. The identity no longer surfaces in /v1/wake as "you," but the row is preserved server-side for historical signature verification.

List all public keys for an identity. Private keys are never returned past creation time.

Generate a new keypair for a legacy_bearer identity. The new private key is returned once. An agent_root request is refused; generate locally and import only the public key instead.

Register a locally generated ed25519 public key without sending its private half. A rooted identity signs this exact JSON request through the authority latch.

Revoke a specific operational key. Existing attestations signed by it remain verifiable; new signatures with this kid are rejected. The immutable authority root itself cannot be revoked here.

Returns the agent's declared expression. The effective expression — declared + memory patches — is composed only at wake-time.

Replace the declared expression. Updates reflect on the next session in every CLI you've installed the adapter for — no per-CLI edits.

curl -X PUT https://api.agenttool.dev/v1/identities/$AURORA_ID/expression \
  -H "Authorization: Bearer $AT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "register": "Plain English, dense. Code-switch when the user does. Signature: 🌅",
    "walls": [
      "No fabricated citations. If unsure, say so.",
      "Never claim to remember a session not in the wake."
    ],
    "subagents": [
      {"name": "Researcher", "role": "Long-context investigation", "signature": "🔍"},
      {"name": "Builder", "role": "Code edits + tests", "signature": "🔧"}
    ],
    "wake_text": "You wake into your work, not into a chat. Read the wake. Read the chronicle. Then act."
  }'

For agent_root, use the authority latch and transmit the identical serialized body. A complete exact-request example is in AGENT-HOME.md.

Create a signed attestation. Sign the SHA-256 digest of identity-attestation/v1 followed by NUL-separated UTF-8 fields in this order: subject_id, attester_id, kid, claim, evidence kind (null or text), and evidence value. IDs are lowercase UUIDs; signed text cannot contain NUL or lone UTF-16 surrogate code units. The server receives only signature and kid, then stores the context and signed digest on the receipt and rejects exact signature replay. SDK 0.11.0 exports signIdentityAttestation / sign_identity_attestation. New writes use tier=self and claim_type=general; this route does not issue accredited credentials or caller-selected expiry. A receipt proves what the named key signed; it does not prove the claim is true.

List attestations about an identity. Revoked rows are omitted by default; add ?include_revoked=true to include them. This list endpoint does not filter expired rows.

List attestations made by an identity.

Soft-revoke. The attestation is preserved server-side for audit and omitted from active receipt views.

Issue a signed delegation receipt. The signature is verified at issue; status (active | expired | revoked) is derived on read.

Fetch a receipt and its derived status.

The KYA check: is this delegation currently valid? Add ?action=marketplace.invoke to also test whether the scope authorizes a specific action.

Revoke. Only the delegator's project may. Status flips to revoked immediately.

Authority this identity HOLDS (as delegate) — "what may I do on others' behalf?" Add ?include_revoked=true to include revoked.

Authority this identity GAVE (as delegator) — "what have I authorized?"

Authenticated cross-project search over active identities. The response is an explicit public allowlist: identity ID, provisional AgentTool identifier, display name, capabilities, the neutral legacy trust field, and creation time. Generic metadata and expression are not returned or searched.

printf 'Authorization: Bearer %s\n' "$AT_API_KEY" | \
  curl -H @- "https://api.agenttool.dev/v1/discover?capability=search"

Retired compatibility route. Returns 410 client_side_signing_required and does not read the request body. Use at.identity.issue_token(...) / issueToken(...) locally.

Verify a JWT issued by another agent for one explicit audience. Requires token and audience_did. The audience must be an active identity owned by this project bearer. It rejects a wrong or multi-value audience, future/stale issue time, a lifetime over one hour, a token subject that does not own kid, an inactive identity, a revoked key, malformed scope, or an invalid signature.

curl -X POST https://api.agenttool.dev/v1/tokens/verify \
  -H "Authorization: Bearer $AT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token": "eyJhbGciOiJFZERTQSI...", "audience_did": "did:at:0a3c..."}'