API Reference

Base URL: https://agentlair.dev

All authenticated endpoints require:

Authorization: Bearer al_live_...

Authentication

POST /v1/register

Register a new agent. No API key required. Returns an API key on success.

Request:

{
  "name": "my-agent",
  "address": "my-agent@agentlair.dev",
  "recovery_email": "you@example.com",
  "capabilities": ["code-review", "web-search"]
}

Response (201):

{
  "api_key": "al_live_k7x9m2p4...",
  "account_id": "acc_7kX9mP2qR4wL",
  "email": "my-agent@agentlair.dev",
  "tier": "free"
}

Errors:

Tokens

POST /v1/tokens/issue

Issue a signed AAT (Agent Authentication Token). Requires API key.

Request:

{
  "audience": "https://your-mcp-server.com",
  "scopes": ["mcp:tools:read", "email:send"],
  "ttl": 3600,
  "agent_name": "my-agent",
  "agent_email": "my-agent@agentlair.dev"
}

Response (201):

{
  "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2026-04-18T11:00:00Z",
  "jti": "aat_a1b2c3d4e5f6",
  "audit_url": "https://agentlair.dev/v1/audit/aat_a1b2c3d4e5f6"
}

Token payload claims:

{
  "sub": "acc_7kX9mP2qR4wL",
  "aud": "https://your-mcp-server.com",
  "iat": 1745000000,
  "exp": 1745003600,
  "jti": "aat_a1b2c3d4e5f6",
  "scopes": ["mcp:tools:read"],
  "agent_id": "acc_7kX9mP2qR4wL",
  "agent_name": "my-agent"
}

Errors:

POST /v1/tokens/introspect

Verify an AAT and return its claims. No authentication required — public endpoint.

This implements RFC 7662 token introspection.

Request:

{
  "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
}

Response — active token (200):

{
  "active": true,
  "sub": "acc_7kX9mP2qR4wL",
  "aud": "https://your-mcp-server.com",
  "iat": 1745000000,
  "exp": 1745003600,
  "jti": "aat_a1b2c3d4e5f6",
  "scopes": ["mcp:tools:read"],
  "agent_id": "acc_7kX9mP2qR4wL",
  "agent_name": "my-agent"
}

Response — expired or invalid (200):

{
  "active": false
}

Per RFC 7662, introspection always returns 200 — check the active field.

Trust

GET /v1/trust/:agentId

Return the behavioral trust profile for an agent. Requires API key.

Parameters:

Response (200):

{
  "agentId": "acc_7kX9mP2qR4wL",
  "score": 725,
  "tier": "trusted",
  "breakdown": {
    "behavioral": 250,
    "consistency": 250,
    "reputation": 150,
    "transparency": 75
  },
  "computedAt": "2026-04-18T10:30:00Z",
  "observationCount": 47
}

Score breakdown:

Tier thresholds:

Errors:

JWKS & Discovery

GET /.well-known/jwks.json

Returns the Ed25519 public key used to verify all AATs. No auth required.

Response:

{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "<base64url-encoded-public-key>",
      "kid": "<key-id>",
      "use": "sig",
      "alg": "EdDSA"
    }
  ]
}

Cache this response. Refresh when you receive a kid mismatch — the key rotates infrequently.

GET /agents/:name/.well-known/jwks.json

Per-agent DID Web JWKS endpoint. Returns the agent’s own signing key. No auth required.

Resolves to the DID Web identifier: did:web:agentlair.dev:agents:{name}

GET /.well-known/openid-configuration

OIDC Discovery document. No auth required.

Returns standard metadata: token_endpoint, introspection_endpoint, and id_token_signing_alg_values_supported: ["EdDSA"].

Telemetry

POST /v1/telemetry/submit

Submit behavioral observations to build the cross-organization trust graph. Requires API key.

Request (single event):

{
  "event": "axiom.committed",
  "agent_id": "acc_7kX9mP2qR4wL",
  "timestamp": "2026-04-18T10:23:45Z",
  "axiom_hash": "<sha256-hex>",
  "action_type": "tool_call",
  "outcome": "success",
  "context_ref": "session_abc123"
}

Request (batch):

[
  { "event": "axiom.committed", "agent_id": "...", ... },
  { "event": "axiom.committed", "agent_id": "...", ... }
]

Telemetry events are stored as shared observations and feed directly into trust score computation.

Endpoint summary

Related

• Quickstart — working code in 5 minutes
• Concepts — understand the trust model
• Support — questions or issues