Back to Developers

API Documentation

Complete reference for the AY Agent Identity API. Create agents with verifiable W3C DID identities, manage guardrails, and verify credentials — all via REST.

Base URLhttps://api.aytwin.ai

Quickstart

Create your first agent in 3 steps. Each agent gets a W3C DID, Ed25519 keypair, API key, and a Verifiable Credential — automatically.

1

Sign up and get an access token

Create an account on aytwin.ai. Authenticate via OIDC to get a Bearer token for the management API.

2

Create an Agent

bash
curl -X POST https://api.aytwin.ai/api/v1/agents \
  -H "Authorization: Bearer <your-oidc-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Commerce Agent",
    "type": "commerce",
    "description": "Handles product search and recommendations",
    "service_endpoint": "https://my-agent.example.com",
    "skills": [
      { "id": "product-search", "name": "Product Search", "description": "Search products by query" }
    ]
  }'

Response

json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Commerce Agent",
  "type": "commerce",
  "did": "did:webvh:QmeSsqqj...:api.aytwin.ai:agents:550e8400-e29b-41d4-a716-446655440000",
  "did_document": { ... },
  "passport_vc": "eyJhbGciOiJFZERTQSIsInR5cCI6InZjK2p3dCJ9...",
  "api_key": "ay_agent_a1b2c3d4e5f6...",
  "created_at": "2026-04-07T12:00:00.000Z"
}
The api_key is shown only once. Store it securely.
3

Verify your agent is alive

bash
curl https://api.aytwin.ai/api/v1/agents/me \
  -H "Authorization: Bearer ay_agent_a1b2c3d4e5f6..."

Authentication

Two authentication methods depending on the caller:

User Management

OIDC Bearer Token

For creating and managing agents

Authorization: Bearer eyJhbG...

Agent Self-Auth

API Key

For agent self-identification

Authorization: Bearer ay_agent_...

Agents API

POST/api/v1/agents

Create a new agent with DID identity, API key, and Verifiable Credential.

🔑 OIDC Bearer Token

Request Body

json
{
  "name": "string (3-100 chars, required)",
  "type": "general | commerce | support | data-processor | iot | creative",
  "description": "string (max 500 chars, optional)",
  "service_endpoint": "URL where your agent runs (optional)",
  "skills": [{ "id": "string", "name": "string", "description": "string" }]
}

Response (201)

Returns agent details including the one-time API key and signed Verifiable Credential.

GET/api/v1/agents

List all agents owned by the authenticated user.

🔑 OIDC Bearer Token
GET/api/v1/agents/:id

Get agent details including daily spending.

🔑 OIDC Bearer Token
PATCH/api/v1/agents/:id/config

Update agent guardrails: kill switch, spending limits.

🔑 OIDC Bearer Token
json
{
  "kill_switch": true,
  "daily_limit_eur": 50.00,
  "max_spend_per_tx_eur": 10.00
}
DELETE/api/v1/agents/:id

Deactivate an agent. Revokes API key, marks DID as deactivated.

🔑 OIDC Bearer Token
GET/api/v1/agents/me

Agent self-identification. Returns agent info, daily spend, and config.

🔑 API Key (ay_agent_...)
bash
curl https://api.aytwin.ai/api/v1/agents/me \
  -H "Authorization: Bearer ay_agent_a1b2c3d4..."

DID Identity

Every agent gets a W3C Decentralized Identifier (DID) using the did:webvh method — the same approach used by the Swiss government e-ID (swiyu). Each DID has a cryptographically verifiable history log, making it tamper-evident without a blockchain.

Identity Hierarchy

👤

Human

did:webvh:...:users:uuidSecure Enclave P-256
🤖

Twin

did:webvh:...:twins:uuidKMS Ed25519
⚡

Agent

did:webvh:...:agents:uuidKMS Ed25519

Fetch DID Document

bash
curl https://api.aytwin.ai/agents/<agent-id>/did.json

Fetch did:webvh Log (verifiable history)

bash
curl https://api.aytwin.ai/agents/<agent-id>/did.jsonl

Returns a JSONL file where each line is a log entry. Entries are hash-chained — modifying any entry breaks the chain. Each entry contains a DataIntegrityProof signed with eddsa-jcs-2022.

Public Endpoints — No Auth Required

GET/users/:id/did.json
GET/twins/:id/did.json
GET/agents/:id/did.json
GET/users/:id/did.jsonl
GET/twins/:id/did.jsonl
GET/agents/:id/did.jsonl

Verifiable Credentials

Every agent receives a Verifiable Credential (VC) at creation — an EdDSA-signed JWT that proves the agent's identity. Anyone with AY's public key can verify it offline, no API call needed.

Decode the VC

The passport_vc is a standard JWT with 3 base64url-encoded parts (header.payload.signature):

bash
# Decode the payload (middle part)
echo "eyJpc3Mi..." | base64 -d | jq .

# Result:
{
  "iss": "did:webvh:Qm...:api.aytwin.ai",
  "sub": "did:webvh:Qm...:agents:550e8400...",
  "vct": "AgentPassport",
  "name": "My Commerce Agent",
  "type": "commerce",
  "owner": "did:webvh:Qm...:users:7c9e6679...",
  "skills": ["product-search"],
  "iat": 1743897600,
  "exp": 1775433600
}

Verify the Signature

javascript
// Node.js — verify with @noble/curves (zero deps beyond this)
import { ed25519 } from '@noble/curves/ed25519';

const [header, payload, signature] = vc_jwt.split('.');
const sigBytes = Buffer.from(signature, 'base64url');
const dataBytes = new TextEncoder().encode(header + '.' + payload);

// Fetch AY's public key from DID Document
const didDoc = await fetch('https://api.aytwin.ai/.well-known/did.json').then(r => r.json());
const publicKeyB64 = didDoc.verificationMethod[0].publicKeyJwk.x;
const publicKey = Buffer.from(publicKeyB64, 'base64url');

const isValid = ed25519.verify(sigBytes, dataBytes, publicKey);
console.log('VC is valid:', isValid);

Token Status List

Check if an agent's credential has been revoked or suspended:

bash
curl https://api.aytwin.ai/api/v1/identity/status-list

# Response:
{
  "status_list": "<DEFLATE compressed, base64url encoded>",
  "bits": 2,
  "total": 42
}

# Status values (2 bits per agent):
# 0 = VALID
# 1 = SUSPENDED (kill_switch active, reversible)
# 2 = REVOKED (agent deleted, permanent)

Rate Limits

POST/agents
5/ 1 hour
POST/did/session
5/ 1 min
POST/did/register
3/ 1 min
GET/agents/me
60/ 1 min
GET/:id/did.json(l)
30/ 1 min
GET/identity/status-list
30/ 1 min
Back to top