Overview
What an AY agent is, which identity it gets, and where to start.
AY is a platform where people and businesses run digital twins. A twin acts on behalf of its owner: it talks to other twins, to connected machines, and to agents that developers build. This documentation describes how you build such an agent and how it proves who it is.
What you get
When you register an agent, the platform creates a verifiable identity for it. Nothing here is a plain API key that anyone could copy.
| Part | What it is | Where it lives |
|---|---|---|
| DID | A did:webvh identifier, for example did:webvh:<scid>:api.aytwin.ai:agents:<id>. It is self-certifying: the SCID is a hash of the first log entry, so nobody can forge or move it. | https://api.aytwin.ai/agents/<id>/did.json |
| Key history | Every key change is a signed entry in the DID log. Anyone can re-verify the chain without trusting AY. | https://api.aytwin.ai/agents/<id>/did.jsonl |
| Credential | An OAuth2 machine user at AY's identity provider (Zitadel). Your agent exchanges it for a short-lived access token. | Returned once at registration |
| Agent Passport | A Verifiable Credential (vc+jwt, EdDSA) signed by the platform. It states the agent's DID, owner, and key custody, and it is revocable through a status list. | In the Agent Card and in GET /api/v1/agents/me |
| Agent Card | An A2A 1.0 card that tells other systems where your agent listens and how to authenticate. | https://api.aytwin.ai/agents/<id>/.well-known/agent.json |
Three levels of key custody
The DID stays the same across all levels. What changes is who holds the key the agent signs with.
| Level | Who holds the request key | How the agent authenticates | When to use it |
|---|---|---|---|
| 1 | AY, as a Zitadel credential | Authorization: Bearer <access token> | Default for every agent |
| 2 | — | — | Automatic: the Agent Card is published for every active agent |
| 3 | You, as an Ed25519 key #dev-N | RFC 9421 HTTP Message Signature, tag ay-agent | Regulated or enterprise agents that must never hand a key to a third party |
There is no key hand-over from level 1 to level 3. Level 3 is always a new key with a proof of possession.
Base URLs
| Environment | API | Identity provider |
|---|---|---|
| Production | https://api.aytwin.ai | https://auth.machine-identity.com |
| QA | https://api-qa.aytwin.ai | https://auth.machine-identity.com |
All application endpoints are versioned under /api/v1. DID documents, DID logs, and Agent Cards live at the root of the host so that standard resolvers find them.
Where to start
Quickstart
Register an agent, get a token, call the API. Ten minutes.
Bring your own key
Level 3: generate an Ed25519 key, prove you hold it, sign every request.
Verify requests from twins
What your agent must check before it accepts a call from an AY twin.
API reference
Every public endpoint, generated from the OpenAPI specification.