Skip to main content
An AgentIdentity is the primary entity in theAuth. It represents one AI agent, a process acting on behalf of a human user. Agents are not users. No password, no session, no OAuth flow. Just a token, a set of permissions, and an audit row for every call.Create one against an existing user ID, hand the token to the agent, and check every action through authorize().

Anatomy

string
Stable identifier (a UUID). Never changes.
string
Bearer token with a ta_ prefix (legacy kv_ tokens are still accepted). Shown once at creation, then SHA-256 hashed. Rotate to replace.
Permission[]
What this agent is allowed to do. Evaluated at every authorize() call.
'active' | 'revoked' | 'expired'
Current state. Revocation is permanent.
string
The user who owns this agent. Must match an existing row in theauth_users (foreign key). Create the row with theauth.user.create({ id, email }).
string
Human-readable label.
'autonomous' | 'delegated' | 'service'
Determines how the agent acquires and uses permissions.
Date
default:"now + agents.tokenExpiry (24h)"
Optional at creation; when omitted it defaults to agents.tokenExpiry from now. Token validation (authorizeByToken) rejects an expired agent and flips its status to expired. authorize(agentId) also compares expiresAt to the clock, so an elapsed agent is denied with code agent_expired (and an audit row) even before its stored status flips.
Record<string, unknown>
default:"{}"
Arbitrary key/value pairs for your own use.

Agent types

Acts independently without requiring human approval on each call, unless a permission constraint mandates it. The standard type for background agents, cron jobs, and AI assistants that run unattended.
Receives permissions from another agent via a delegation chain rather than having them declared at creation. Use this for ephemeral sub-agents spun up to complete one task, then discarded.
Long-lived identity for infrastructure, such as an MCP server or an internal microservice that calls other services on behalf of users. Treat it like a service account.

Lifecycle

1

Create

The token is returned once at creation. theAuth stores only the SHA-256 hash, so the plaintext cannot be recovered later. Save it immediately or rotate to get a new one.
2

Authenticate

Tokens use the ta_ prefix followed by 32 random bytes encoded as base64url (43 characters, 46 in total). Pass as a Bearer credential:
Hash-only storage: a full database dump cannot reveal an active token. There are no secrets to rotate after a DB breach, only the tokens themselves.
3

Authorize

When a caller only has the raw token, use authorizeByToken in your HTTP middleware:
The token is hashed and looked up in the database, then permissions are evaluated and the decision is written to the audit log. No JWTs, no network round-trip. This path checks the agent’s own permissions only; permissions it holds through delegation are applied by authorize(agentId, ...).
Isometric diagram of an agent request passes the theAuth gate, which checks permissions and writes an audit record, before reaching your MCP server or API. The result is allowed: true with an audit id.

An authorize() call checks permissions, writes the audit record and returns allowed with an auditId.

4

Rotate

Rotation issues a new token and immediately invalidates the old one. It is a single update, so there is no window where both are valid. Only active agents can be rotated.
Rotate on a schedule, or any time you suspect a token has been exposed.
5

Update or list

Permission updates take effect immediately. In-flight requests that already passed authorization are not affected.
6

Revoke

Each attempt by a revoked or expired agent is still written to the audit log as a denied row with the reason agent_revoked or agent_expired. See what gets recorded. policy.evaluate() denies a revoked, suspended or expired agent with POLICY_AGENT_INACTIVE.In the TypeScript package, agent.revoke() also revokes every active delegation chain the agent gave or received, and the chains downstream of them. The call returns { revokedDelegations } with the chain ids, writes one agent.cascade.revoked audit row, and fires onAgentRevoke.
Revocation is permanent. There is no un-revoke. To restore access, create a new agent.

Token format

New agent tokens look like ta_ followed by 43 base64url characters (32 random bytes, 46 characters in total). The first 11 characters are stored as a non-secret lookup prefix; the rest is only ever stored as a SHA-256 hash. Tokens issued by earlier releases start with kv_ (the old kavachOS name). They are still accepted everywhere, and their stored rows are not rewritten, so no migration is needed. Nothing new is issued with kv_. To move an agent off a legacy token, rotate it. The old token stops working at once and the new one starts with ta_:

Secret scanning

Use this regex for GitHub secret scanning custom patterns and gitleaks. It matches both the current and the legacy prefix. The final character is limited to the 16 values a 32 byte base64url string can end with.
A gitleaks rule:

Limits

The default is 10 active agents per user. Raise at initialization:
The cap counts active agents. Creating one past it throws a plain Error with the message User <id> has reached the maximum of <n> active agents. (there is no dedicated error code, and the REST endpoint reports it as 500 INTERNAL_ERROR).

What agents aren’t

An agent is not a user. It has no email, no password, no session, no OAuth account. It has a bearer token and a permission set. If you find yourself reaching for password reset, email verification, or social sign-in on an agent, you want a user, not an agent. Create the user first, then create agents that the user owns.

Next steps

Permission engine

Define what agents can and cannot do.

Delegation chains

Let agents delegate access to sub-agents.

Ephemeral sessions

Short-lived agents for one-off tasks.

Framework adapters

Use agents in HTTP middleware.
Last modified on October 18, 2026