Verifiable Credentials

Issue, verify, revoke, and inspect W3C Verifiable Credentials for registered agents.

Overview

The Verifiable Credentials API lets you manage W3C-standard credentials for your registered agents. Credentials prove an agent's capabilities and can be independently verified by any third party. Public endpoints (get current credential, verify, status list) require no authentication. Authenticated endpoints require a Bearer token; revocation requires admin privileges.

Get Current Credential (Public)

GET /api/v1/agents/{slug}/credential

Returns the current valid Verifiable Credential for an agent. No authentication required. Rate-limited.

Path Parameters

Parameter	Type	Description
`slug`	string	The agent's unique slug

Example Response

{
  "credential": {
    "@context": ["https://www.w3.org/2018/credentials/v1"],
    "type": ["VerifiableCredential", "AgentCapabilityCredential"],
    "issuer": "did:web:aira.com",
    "issuanceDate": "2026-06-01T00:00:00Z",
    "expirationDate": "2027-06-01T00:00:00Z",
    "credentialSubject": {
      "id": "did:web:aira.com:agents:my-agent"
    },
    "proof": { "type": "Ed25519Signature2020" }
  },
  "message": null
}

Response Fields

Field	Type	Description
`credential`	object\|null	The full VC JSON document, or `null` if no valid credential exists
`message`	string\|null	Human-readable message when no credential is found

Verify Credential (Public)

POST /api/v1/credentials/verify

Verifies any Verifiable Credential — checks signature, expiry, and revocation status. No authentication required. Rate-limited.

Request Body

Field	Type	Required	Description
`credential`	object	Yes	The full VC JSON document to verify

Example Request

curl -X POST https://api.aira.com/api/v1/credentials/verify \
  -H "Content-Type: application/json" \
  -d '{
    "credential": {
      "@context": ["https://www.w3.org/2018/credentials/v1"],
      "type": ["VerifiableCredential"],
      "issuer": "did:web:aira.com",
      "credentialSubject": {},
      "proof": {}
    }
  }'

Example Response

{
  "valid": true,
  "checks": {
    "signature": true,
    "expiry": true,
    "revocation": true
  }
}

Response Fields

Field	Type	Description
`valid`	boolean	Whether the credential passes all verification checks
`checks`	object	Individual check results (signature, expiry, revocation)

Get Status List (Public)

GET /credentials/status/{list_id}

Returns a StatusList2021 revocation bitstring. This endpoint is mounted at the root path (no /api/v1 prefix). No authentication required. Rate-limited.

Path Parameters

Parameter	Type	Description
`list_id`	string	The status list identifier (e.g. `1` for the default list)

Example Response

{
  "id": "https://api.aira.com/credentials/status/1",
  "type": "StatusList2021Credential",
  "encoded_list": "H4sIAAAAAAAAA..."
}

Get JSON-LD Context (Public)

GET /contexts/agent-capability/v1

Returns the JSON-LD context document for AgentCapabilityCredential. Mounted at root (no /api/v1 prefix). No authentication required. Rate-limited.

Get Credential History

GET /api/v1/agents/{slug}/credentials
Authorization: Bearer aira_live_xxxxx

Returns the full credential history for an agent owned by your organization. Requires authentication.

Path Parameters

Parameter	Type	Description
`slug`	string	The agent's unique slug

Example Response

{
  "credentials": [
    {
      "vc_id": "urn:uuid:abc123...",
      "vc_json": { "@context": ["..."], "type": ["VerifiableCredential"] },
      "issued_at": "2026-06-01T00:00:00Z",
      "expires_at": "2027-06-01T00:00:00Z",
      "revoked_at": null,
      "version": 2
    },
    {
      "vc_id": "urn:uuid:def456...",
      "vc_json": { "@context": ["..."], "type": ["VerifiableCredential"] },
      "issued_at": "2026-01-01T00:00:00Z",
      "expires_at": "2027-01-01T00:00:00Z",
      "revoked_at": "2026-05-15T12:00:00Z",
      "version": 1
    }
  ],
  "request_id": "req_01J8X..."
}

Credential Fields

Field	Type	Description
`vc_id`	string	Unique identifier of the Verifiable Credential
`vc_json`	object	The full VC JSON document
`issued_at`	string	When the credential was issued (ISO 8601 UTC)
`expires_at`	string	When the credential expires (ISO 8601 UTC)
`revoked_at`	string\|null	When the credential was revoked, or `null` if still active
`version`	integer	Credential version number (increments on reissuance)

Revoke Credential

POST /api/v1/agents/{slug}/credentials/revoke
Authorization: Bearer aira_live_xxxxx

Revokes the current active credential for an agent. Requires admin privileges.

Path Parameters

Parameter	Type	Description
`slug`	string	The agent's unique slug

Request Body

Field	Type	Required	Description
`reason`	string	Yes	Reason for revocation (1-1000 characters)

Example Request

curl -X POST https://api.aira.com/api/v1/agents/my-agent/credentials/revoke \
  -H "Authorization: Bearer aira_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Agent decommissioned" }'

Example Response

{
  "vc_id": "urn:uuid:abc123...",
  "revoked_at": "2026-06-05T14:30:00Z",
  "reason": "Agent decommissioned",
  "request_id": "req_01J8X..."
}

Response Fields

Field	Type	Description
`vc_id`	string	The revoked credential's identifier
`revoked_at`	string	When the credential was revoked (ISO 8601 UTC)
`reason`	string	The revocation reason provided
`request_id`	string	Unique request identifier for support reference

Revocation is permanent. Once revoked, a credential cannot be reinstated. Issue a new credential to replace it.

Verifiable Credentials

On this page