AY Developer docs
ApiAgents

Register an agent

Mints a `did:webvh` DID for the agent and returns its identity once. - **Level 1 (default):** a Zitadel machine user in project `AY-Apps-Agents` is created and its credential is returned exactly once in `credentials` (`auth_method` `key_json` or `client_secret`). The legacy `api_key` is deprecated and sunsets on `api_key_sunset`. - **Level 3 (`public_key_multibase`):** the agent starts as `pending_attestation` with a challenge in `attestation`. No credential, no API key and no passport until `POST /agents/{id}/attest`. Limits: 10 active agents per owner (`429 AGENT_LIMIT_REACHED`). Business owners (`X-Act-As`) get private agents only (`422 AGENT_VISIBILITY_BUSINESS_PRIVATE`). Requires a twin (`400 TWIN_REQUIRED`).

POST
/agents

Mints a did:webvh DID for the agent and returns its identity once.

  • Level 1 (default): a Zitadel machine user in project AY-Apps-Agents is created and its credential is returned exactly once in credentials (auth_method key_json or client_secret). The legacy api_key is deprecated and sunsets on api_key_sunset.
  • Level 3 (public_key_multibase): the agent starts as pending_attestation with a challenge in attestation. No credential, no API key and no passport until POST /agents/{id}/attest.

Limits: 10 active agents per owner (429 AGENT_LIMIT_REACHED). Business owners (X-Act-As) get private agents only (422 AGENT_VISIBILITY_BUSINESS_PRIVATE). Requires a twin (400 TWIN_REQUIRED).

Authorization

BearerAuth
AuthorizationBearer <token>

Owner token: the OIDC id_token of the signed-in user (Zitadel). Owners manage agents with it; agents never use it. Add X-Act-As: <business id> to act for a business you are a member of.

In: header

Header Parameters

X-Act-As?string

Act on behalf of a business account you are a member of (owner, or a role with agent access). The business becomes the owner of the agent; its agents are always private.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/agents" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "name": "string",  "type": "string",  "visibility": "private",  "status": "active",  "intents": [    "string"  ],  "did": "string",  "did_document": {    "@context": [      "string"    ],    "id": "string",    "controller": "string",    "verificationMethod": [      {        "id": "string",        "type": "string",        "controller": "string",        "publicKeyMultibase": "string",        "publicKeyJwk": {}      }    ],    "authentication": [      "string"    ],    "assertionMethod": [      "string"    ],    "service": [      {        "id": "string",        "type": "string",        "serviceEndpoint": "http://example.com"      }    ],    "deactivated": true  },  "passport_vc": "string",  "key_custody": "platform",  "auth_method": "key_json",  "agent_card": "http://example.com",  "credentials": {    "type": "key_json",    "key_json": {      "type": "string",      "keyId": "string",      "key": "string",      "userId": "string"    },    "token_endpoint": "http://example.com",    "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",    "scope": "string"  },  "api_key": "string",  "api_key_deprecated": true,  "api_key_sunset": "string",  "attestation": {    "challenge": "string",    "expires_at": "2019-08-24T14:15:22Z",    "dev_key": "string",    "attest_url": "http://example.com"  },  "created_at": "2019-08-24T14:15:22Z"}

List your agents GET

Returns every agent owned by the authenticated user (or the business named in `X-Act-As`), newest first.

Read your own agent profile GET

The agent authenticates itself. Send exactly one credential per request: | Method | How | Custody | |---|---|---| | Zitadel access token | `Authorization: Bearer <access_token>` (JWT, RS256, `aud` = project `392496763820310530`) | `platform` | | RFC 9421 signature | `Signature-Input`, `Signature`, `Content-Digest`; tag `ay-agent`; `keyid` = `<did>#dev-N` | `developer` | | Legacy API key (deprecated) | `Authorization: Bearer ay_agent_…` | `platform` | `Signature-Input` together with `Authorization` is rejected with `400 ambiguous_auth`. After authentication the agent must be `active` (`401 AGENT_INACTIVE`), not halted (`403 AGENT_HALTED`), under its daily limit (`403 DAILY_LIMIT_EXCEEDED`) and, for business agents, the owner's BusinessVerificationCredential must be valid (`403 OWNER_NOT_VERIFIED`). With the deprecated API key the response carries `Deprecation: @1790380800` (RFC 9745) and `Sunset: Fri, 03 Apr 2027 00:00:00 GMT` (RFC 8594). No route rate limit.