Decentralized Identifiers (DID) Resolve DID documents, inspect agent identity, rotate keys, and fetch A2A agent cards.
Aira assigns each registered agent a W3C-compliant did:web decentralized identifier backed by an Ed25519 keypair. The DID endpoints let you resolve DID documents (publicly or authenticated), rotate an agent's keys, resolve remote DIDs, and fetch A2A agent cards.
The following endpoints are publicly accessible (no authentication required). They are rate-limited and mounted at the site root -- not under /api/v1.
GET /agents/{agent_slug}/did.json Returns the W3C DID document for an agent. DID documents are always publicly resolvable regardless of the agent's public flag, as required by the did:web specification.
Parameter Type Required Description agent_slugstring Yes The agent's URL-safe slug
curl https://api.airaproof.com/agents/procurement-agent/did.json { "@context" : [ "https://www.w3.org/ns/did/v1" , "https://w3id.org/security/suites/ed25519-2020/v1" ], "id" : "did:web:api.airaproof.com:agents:procurement-agent" , "verificationMethod" : [ { "id" : "did:web:api.airaproof.com:agents:procurement-agent#key-1" , "type" : "Ed25519VerificationKey2020" , "controller" : "did:web:api.airaproof.com:agents:procurement-agent" , "publicKeyMultibase" : "z6Mkf5rG..." } ], "authentication" : [ "did:web:api.airaproof.com:agents:procurement-agent#key-1" ], "assertionMethod" : [ "did:web:api.airaproof.com:agents:procurement-agent#key-1" ], "service" : [ { "id" : "did:web:api.airaproof.com:agents:procurement-agent#aira" , "type" : "AiraAgent" , "serviceEndpoint" : "https://api.airaproof.com/api/v1/agents/procurement-agent" } ] } Status Code Description 404 NOT_FOUNDAgent does not exist or has no DID document
GET /.well-known/did.json Returns Aira's own root DID document, signed with the platform's Ed25519 key. This is the trust anchor for verifying agent DIDs issued by this Aira instance.
curl https://api.airaproof.com/.well-known/did.json { "@context" : [ "https://www.w3.org/ns/did/v1" , "https://w3id.org/security/suites/ed25519-2020/v1" ], "id" : "did:web:api.airaproof.com" , "verificationMethod" : [ { "id" : "did:web:api.airaproof.com#key-1" , "type" : "Ed25519VerificationKey2020" , "controller" : "did:web:api.airaproof.com" , "publicKeyMultibase" : "z6Mkf5rG..." } ], "authentication" : [ "did:web:api.airaproof.com#key-1" ], "assertionMethod" : [ "did:web:api.airaproof.com#key-1" ], "service" : [ { "id" : "did:web:api.airaproof.com#aira-platform" , "type" : "AiraPlatform" , "serviceEndpoint" : "https://api.airaproof.com/api/v1" } ] } GET /agents/{agent_slug}/.well-known/agent-card.json Returns the A2A (Agent-to-Agent) card for an agent. Agent cards provide discovery metadata including capabilities, authentication methods, and DID.
Parameter Type Required Description agent_slugstring Yes The agent's URL-safe slug
curl https://api.airaproof.com/agents/procurement-agent/.well-known/agent-card.json { "name" : "Procurement Agent" , "description" : "Handles purchase orders and vendor management" , "url" : "https://api.airaproof.com/agents/procurement-agent" , "did" : "did:web:api.airaproof.com:agents:procurement-agent" , "capabilities" : [ "transaction" , "decision" ], "authentication" : { "type" : "oauth2" , "authorizationUrl" : "https://api.airaproof.com/oauth/authorize" }, "aira" : { "notarization" : true , "mutual_signing" : false , "reputation_score" : null } } Field Type Description namestring The agent's display name descriptionstring | null Human-readable description of the agent urlstring The agent's public URL didstring The agent's did:web identifier capabilitiesstring[] List of capabilities the agent supports authenticationobject Authentication method metadata airaobject Aira-specific metadata (notarization, mutual signing, reputation)
Status Code Description 404 NOT_FOUNDAgent does not exist
All endpoints below require a Bearer token (Authorization: Bearer aira_live_xxxxx). Base URL: https://api.airaproof.com/api/v1
GET /api/v1/agents/{agent_slug}/did Authorization : Bearer aira_live_xxxxx Returns full DID information for an agent, including the DID document, creation timestamp, and document version. The agent must belong to the authenticated organization.
Parameter Type Required Description agent_slugstring Yes The agent's URL-safe slug
curl https://api.airaproof.com/api/v1/agents/procurement-agent/did \ -H "Authorization: Bearer aira_live_xxxxx" { "did" : "did:web:api.airaproof.com:agents:procurement-agent" , "document" : { "@context" : [ "https://www.w3.org/ns/did/v1" , "https://w3id.org/security/suites/ed25519-2020/v1" ], "id" : "did:web:api.airaproof.com:agents:procurement-agent" , "verificationMethod" : [ { "id" : "did:web:api.airaproof.com:agents:procurement-agent#key-1" , "type" : "Ed25519VerificationKey2020" , "controller" : "did:web:api.airaproof.com:agents:procurement-agent" , "publicKeyMultibase" : "z6Mkf5rG..." } ], "authentication" : [ "did:web:api.airaproof.com:agents:procurement-agent#key-1" ], "assertionMethod" : [ "did:web:api.airaproof.com:agents:procurement-agent#key-1" ], "service" : [ { "id" : "did:web:api.airaproof.com:agents:procurement-agent#aira" , "type" : "AiraAgent" , "serviceEndpoint" : "https://api.airaproof.com/api/v1/agents/procurement-agent" } ] }, "created_at" : "2026-06-01T10:30:00Z" , "version" : 1 , "request_id" : "req_01J9E..." } Field Type Description didstring The agent's did:web identifier documentobject The full W3C DID document (empty object if no key has been generated yet) created_atstring | null When the DID was first created (ISO 8601) versioninteger The DID document version (increments on each key rotation) request_idstring Request ID for tracing
Status Code Description 404 NOT_FOUNDAgent does not exist in your organization
POST /api/v1/agents/{agent_slug}/did/rotate Authorization : Bearer aira_live_xxxxx Rotates an agent's Ed25519 DID keypair. Generates a new keypair, updates the DID document, and increments the document version. The old key is discarded. Requires admin role.
This operation is audited as agent.did.rotated.
Parameter Type Required Description agent_slugstring Yes The agent's URL-safe slug
curl -X POST https://api.airaproof.com/api/v1/agents/procurement-agent/did/rotate \ -H "Authorization: Bearer aira_live_xxxxx" { "new_did" : "did:web:api.airaproof.com:agents:procurement-agent" , "new_version" : 2 , "request_id" : "req_01J9F..." } Field Type Description new_didstring The agent's DID (unchanged -- only the key rotates) new_versioninteger The new document version after rotation request_idstring Request ID for tracing
Status Code Description 403 FORBIDDENCaller does not have admin role 404 NOT_FOUNDAgent does not exist in your organization
POST /api/v1/dids/resolve Authorization : Bearer aira_live_xxxxx Resolves a remote did:web DID document by fetching it over HTTPS. Results are cached in Redis for 5 minutes.
Field Type Required Description didstring Yes A did:web identifier to resolve (must start with did:web:)
curl -X POST https://api.airaproof.com/api/v1/dids/resolve \ -H "Authorization: Bearer aira_live_xxxxx" \ -H "Content-Type: application/json" \ -d '{ "did": "did:web:example.com:agents:their-agent" }' { "did" : "did:web:example.com:agents:their-agent" , "document" : { "@context" : [ "https://www.w3.org/ns/did/v1" , "https://w3id.org/security/suites/ed25519-2020/v1" ], "id" : "did:web:example.com:agents:their-agent" , "verificationMethod" : [ { "id" : "did:web:example.com:agents:their-agent#key-1" , "type" : "Ed25519VerificationKey2020" , "controller" : "did:web:example.com:agents:their-agent" , "publicKeyMultibase" : "z6Mkq8bT..." } ], "authentication" : [ "did:web:example.com:agents:their-agent#key-1" ], "assertionMethod" : [ "did:web:example.com:agents:their-agent#key-1" ] }, "cached" : false , "request_id" : "req_01J9G..." } Field Type Description didstring The DID that was resolved documentobject The fetched W3C DID document cachedboolean Whether the result was served from cache request_idstring Request ID for tracing
Status Code Description 422 VALIDATION_ERRORThe did field is missing or does not start with did:web:
All DID documents returned by Aira follow the W3C DID Core specification:
Field Type Description @contextstring[] JSON-LD context URIs idstring The DID identifier verificationMethodobject[] Public keys associated with the DID authenticationstring[] Key IDs authorized for authentication assertionMethodstring[] Key IDs authorized for making assertions serviceobject[] Service endpoints associated with the DID
Each verification method contains:
Field Type Description idstring Key identifier (DID + fragment, e.g. #key-1) typestring Always Ed25519VerificationKey2020 controllerstring The DID that controls this key publicKeyMultibasestring The public key encoded as multibase (base58btc, z prefix)