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>
• X-Bulwark-App-Id: <app-id> — Optional. Filters results to a specific application.

Body

{
  "name": "my-assistant",
  "description": "Customer support AI agent",
  "type": "llm_agent",
  "trust_level": "medium"
}

Trust levels: low, medium, high, critical. Defaults to low if omitted. high and critical require admin role.

Response 201

{
  "agent": {
    "id": "agent_01j...",
    "tenant_id": "ten_01j...",
    "name": "my-assistant",
    "description": "Customer support AI agent",
    "type": "llm_agent",
    "status": "active",
    "trust_level": "medium",
    "auth_method": "api_key",
    "capabilities": [],
    "owner_user_id": null,
    "created_at": "2026-03-18T00:00:00Z",
    "updated_at": "2026-03-18T00:00:00Z"
  },
  "api_key": "bwk_agent_live_..."
}

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

List Agents

GET /api/v1/agents

Response 200

{
  "agents": [
    {
      "id": "agent_01j...",
      "tenant_id": "ten_01j...",
      "name": "my-assistant",
      "description": "Customer support AI agent",
      "type": "llm_agent",
      "status": "active",
      "trust_level": "medium",
      "auth_method": "api_key",
      "capabilities": [],
      "owner_user_id": null,
      "last_active_at": "2026-03-18T12:00:00Z",
      "created_at": "2026-03-18T00:00:00Z",
      "updated_at": "2026-03-18T00:00:00Z"
    }
  ]
}

Get Agent

GET /api/v1/agents/{id}

Response 200

{
  "id": "agent_01j...",
  "tenant_id": "ten_01j...",
  "name": "my-assistant",
  "description": "Customer support AI agent",
  "type": "llm_agent",
  "status": "active",
  "trust_level": "medium",
  "auth_method": "api_key",
  "capabilities": [],
  "owner_user_id": null,
  "last_active_at": "2026-03-18T12:00:00Z",
  "created_at": "2026-03-18T00:00:00Z",
  "updated_at": "2026-03-18T00:00:00Z"
}

Revoke Agent

DELETE /api/v1/agents/{id}

Immediately invalidates all tokens issued to this agent.

Response 200

{
  "status": "revoked"
}

Rotate Agent API Key

POST /api/v1/agents/{id}/rotate

Issues a new API key and invalidates the old one.

Response 200

{
  "api_key": "bwk_agent_live_..."
}