Agent Identity

In Bulwark, AI agents are first-class principals — they have their own identity, credentials, and access policies, just like human users.

What is an Agent Principal?

Traditional auth systems model only humans. An agent principal is a stable, auditable identity for an AI agent that:

  • Has its own API key and cryptographic identity
  • Is assigned a trust level that governs what it can do
  • Is registered with explicit scopes defining its permissions
  • Can be revoked independently of the user it operates on behalf of

Agent Lifecycle

Register → Issue API Key → Create Session → Act → Complete Session
    ↓                                                      ↓
  Stored in                                         Audit trail written
  Agent Registry                                    Session invalidated

Registration

const agent = await bulwark.agents.register({
  name: "customer-support-bot",
  scopes: ["read:customers", "write:tickets"],
  trustLevel: "medium",
});

Session-scoped operation

Every action an agent takes should happen within a session. Sessions:

  • Bind the agent to a specific user (or run autonomously)
  • Scope credentials to the minimum required
  • Are recorded in the audit trail
  • Expire automatically via TTL

Trust Levels

Trust level determines what the agent is allowed to do:

| Level | Description | Typical Use | |-------|-------------|-------------| | low | Read-only, no external calls | Summarization, analysis | | medium | Read/write, limited external access | Customer support, scheduling | | high | Broad access, financial or PII operations | Billing agents, HR agents | | critical | Full access, requires CIBA for sensitive actions | Executive assistants, compliance agents |

Delegated Identity

An agent can create attenuated tokens for sub-agents with reduced scope:

const subToken = await session.attenuate({
  scopes: ["read:customers"], // subset of agent's scopes
  ttl: 600,                   // 10 minutes
  caveats: [
    { type: "resource", value: "customer_id:cust_abc" }
  ],
});

The sub-agent receives a Biscuit token that cannot escalate its own privileges — even if compromised.

Separation from User Identity

An agent's identity is separate from the user it acts for:

User (usr_01j...)     ←→    Agent (agent_01j...)
  Human identity             AI agent identity
  JWT auth                   Biscuit token auth
  Browser/mobile             Server/process
  Long-lived session         Task-scoped session

This separation means:

  • Revoking an agent doesn't log out the user
  • An agent's audit trail is separate from the user's activity
  • Scopes are enforced independently for agents and users