Agent Endpoints

Manage AI agent principals — registration, listing, inspection, and revocation.

Register Agent

POST /api/v1/agents

Headers

• Authorization: Bearer <apiKey>
• X-Bulwark-Tenant: <tenant-id>

Body

{
  "name": "my-assistant",
  "description": "Customer support AI agent",
  "scopes": ["read:customers", "write:tickets"],
  "trustLevel": "medium",
  "metadata": {
    "model": "claude-3-5-sonnet",
    "owner": "team-support"
  }
}

Trust levels: low, medium, high, critical

Response 201

{
  "data": {
    "agentId": "agent_01j...",
    "name": "my-assistant",
    "apiKey": "bwk_agent_...",
    "scopes": ["read:customers", "write:tickets"],
    "trustLevel": "medium",
    "createdAt": "2026-03-18T00:00:00Z"
  }
}

Important: apiKey is returned only once. Store it securely.

List Agents

GET /api/v1/agents

Query Parameters

• limit — Results per page (default: 20, max: 100)
• cursor — Pagination cursor
• trustLevel — Filter by trust level
• status — active or revoked

Response 200

{
  "data": [
    {
      "agentId": "agent_01j...",
      "name": "my-assistant",
      "trustLevel": "medium",
      "status": "active",
      "lastSeenAt": "2026-03-18T12:00:00Z"
    }
  ],
  "pagination": { "cursor": "...", "hasMore": false }
}

Get Agent

GET /api/v1/agents/{agentId}

Response 200

{
  "data": {
    "agentId": "agent_01j...",
    "name": "my-assistant",
    "description": "Customer support AI agent",
    "scopes": ["read:customers", "write:tickets"],
    "trustLevel": "medium",
    "status": "active",
    "metadata": { "model": "claude-3-5-sonnet" },
    "createdAt": "2026-03-18T00:00:00Z",
    "lastSeenAt": "2026-03-18T12:00:00Z"
  }
}

Revoke Agent

DELETE /api/v1/agents/{agentId}

Immediately invalidates all tokens issued to this agent.

Response 200

{
  "data": {
    "agentId": "agent_01j...",
    "status": "revoked",
    "revokedAt": "2026-03-18T13:00:00Z"
  }
}

Rotate Agent API Key

POST /api/v1/agents/{agentId}/rotate-key

Issues a new API key and invalidates the old one.

Response 200

{
  "data": {
    "agentId": "agent_01j...",
    "apiKey": "bwk_agent_...",
    "rotatedAt": "2026-03-18T13:00:00Z"
  }
}