---
title: "Identity for AI agents: scoped tokens and audit"
description: "Give each AI agent its own kv_ token, wildcard permissions, depth-limited delegation, budget policies, approval gates and a per-action audit trail. MIT."
canonical: https://theauth.dev/agent-identity/
lastmod: 2026-10-31
---

Agent identity

# Identity for AI agents

An agent is not a user and not a shared API key. In theAuth it is an identity with an owner, its own kv_ bearer token, scoped permissions, an optional expiry and an audit row for every decision.

[Read the quickstart](https://docs.theauth.dev/quickstart) [Agents docs](https://docs.theauth.dev/agents)

agent recordactive

authorize(agent.id, read, mcp:github:repos) => allowed, auditId aud_...

Agent lifecycle

## From first credential to instant revoke

Five moments in the life of one agent. Scroll to step through them, or use the list.

agent credentialactive

scopes

mcp:github:* [read]file:reports/* [read]

delegationmaxDepth 2

- plannermcp:github:* [read, comment]
- code-reviewermcp:github:pulls [read, comment]
- diff-fetchermcp:github:pulls [read]

Each hop can only narrow. A wider request is refused when the link is created.

approval neededpending

**github-reader** wants to delete file:prod-data/export.csv

Approve onceDeny

The agent waits. A denial or a timeout means no.

audit loggithub-reader

- allow read mcp:github:repos aud_71c2
- allow read mcp:github:pulls aud_71c3
- hold delete file:prod-data/* aud_71c4
- deny read mcp:slack:channels aud_71c5

agents1 revoked

**github-reader revoked**
authorize() => allowed: false

Links created downstream of this agent are revoked with it. It applies on the next call, not to work already run.

Anatomy

## What the token is, and is not

Tokens are kv_ plus 32 random bytes. The plaintext is returned once at creation. Only a SHA-256 hash is stored, so a database dump does not reveal a live token. Rotation issues a new token and invalidates the old one.

type: autonomousRuns unattended with the permissions declared at creation.

type: delegatedReceives permissions through a delegation chain. Suited to short-lived sub-agents.

type: serviceLong-lived identity for infrastructure such as an MCP server.

limitsDefault cap of 10 active agents per user, configurable with agents.maxPerUser.

revokePermanent. Later authorize calls return allowed: false.

Permissions

## Wildcard matching, then constraints

A permission is a colon-separated resource pattern plus actions. A * segment matches everything from that position on. Constraints must all pass: maxCallsPerHour, allowedArgPatterns, timeWindow (UTC), ipAllowlist (CIDR) and requireApproval.

Matching behavior from the policy source (policy/abac.ts)

| Pattern | Resource | Match |
| --- | --- | --- |
| mcp:github:* | mcp:github:repos | Yes |
| mcp:github:* | mcp:github:repos:comments | Yes, * covers the remaining segments |
| mcp:github:* | mcp:slack:channels | No |
| mcp:github:repos | mcp:github:repos:comments | No, exact patterns must match in length |
| * | any | Yes |

How a delegation chain is checked

## Narrow at every hop, capped by depth

An orchestrator hands a subset of its permissions to a sub-agent. Two checks run when the link is created, and more run on every call.

1. human**user-123**
   - mcp:github:* [read, comment]
   - mcp:slack:* [read]
   - file:reports/* [read]
2. agent**planner**
   - mcp:github:* [read, comment]
   - mcp:slack:* [read]
   - file:reports/* [read]
3. sub-agent**diff-fetcher**
   - mcp:github:pulls [read]
   - mcp:github:* [read, comment]

Struck-through scopes are what the previous holder had and this hop does not. A link can only hand down a subset of what its parent holds, and the depth limit stops the chain at maxDepth.

1. plannerautonomous

   mcp:github:* [read, write, comment]

   delegate(planner, code-reviewer, mcp:github:pulls [read, comment], maxDepth 2)

   **Subset.** The parent must hold every permission it hands over. Wider resources or new actions are rejected.
2. code-reviewerdelegated, depth 1

   mcp:github:pulls [read, comment]

   delegate(code-reviewer, diff-fetcher, ..., maxDepth 2)

   **Depth.** New depth is the deepest incoming link plus one. It must not exceed this call's maxDepth (default 3). Depth 2 passes.
3. diff-fetcherdelegated, depth 2

   mcp:github:pulls [read]

   delegate(diff-fetcher, another-agent, ..., maxDepth 2)

   **Rejected.** Depth 3 exceeds the maximum of 2, which prevents unbounded chains.
4. another-agentno link created

On every authorize() call

1. A**Status.** The agent must exist and be active, not revoked or expired.
2. B**Own permissions.** Pattern, action and constraints are evaluated first.
3. C**Delegated permissions.** If B denies, grants from active, unexpired chains are tried.
4. D**Audit.** The decision is written and its auditId returned.

Revoking a link also revokes every link created downstream of it. It takes effect on the next authorize call, not on operations already running. Delegated grants carry resource and actions only. See [delegation docs](https://docs.theauth.dev/delegation).

Sensitive actions

## Approval, budgets and audit

### Denied until approved

A permission with `requireApproval: true` is denied. Your app catches the denial.

### Request created

`approval.request()` persists it with a default TTL of 5 minutes and fires your `webhookUrl` or `onApprovalNeeded`.

### Human decides

Your UI calls `approval.approve()` or `deny()`. Delivering the notification is your app's job.

### Agent retries

The retried action passes the permission check once the request is approved.

- **Budget policies** cap token cost and call counts per agent, user or tenant. On breach: warn, throttle, block or revoke. [Budget docs](https://docs.theauth.dev/budget-policies).
- **Audit trail.** Each entry records agent, owner, action, resource, parameters, result (allowed, denied, rate_limited), duration and timestamp. Export as JSON or CSV. [Audit docs](https://docs.theauth.dev/audit).
- **Trust score.** Each agent gets a 0 to 100 score from its age, call volume and audit history. See [trust scoring](https://docs.theauth.dev/trust). Automatic anomaly detection is not shipped: the `anomaly.detected` event name is reserved, but nothing emits it yet.

Honest limit

Approval requests are stored by theAuth, but it ships no approval UI and does not deliver the notification. You build that step.

Create and authorize

## Create an agent, authorize an action

The same calls run on Postgres, SQLite, MySQL or D1. Go has its own agent model on top of OAuth client credentials, documented in the [Go package](https://pkg.go.dev/github.com/glincker/theauth-go/v2).

agent.ts

```ts
import { createTheAuth } from "@glinr/theauth";

const auth = await createTheAuth({
  database: { provider: "postgres", url: process.env.DATABASE_URL },
});

// Create an AI agent with scoped MCP permissions
const agent = await auth.agent.create({
  ownerId: "user-123",
  name: "github-reader",
  type: "autonomous",
  permissions: [{ resource: "mcp:github:*", actions: ["read"] }],
});

const result = await auth.authorize(agent.id, {
  action: "read",
  resource: "mcp:github:repos",
});
// { allowed: true, auditId: "aud_..." }
```

Your code calls authorize() for an agent: theAuth checks the agent's permissions, writes the decision to the audit log and returns allowed plus an auditId before the action runs on your MCP server or API.

Compared

## Agent identity, shared API keys, human sessions

General patterns, not claims about any vendor. A shared key is often the right call for one service talking to one API you control.

| Question | Shared API key | Human session | theAuth agent |
| --- | --- | --- | --- |
| Who is it? | Whoever holds the string | A person at a browser | One named agent with an owner |
| Scope | Whatever the key allows, usually coarse | The user's full rights | Resource and action patterns plus constraints |
| Handing work to a sub-agent | Copy the key | Not designed for it | Narrower delegation with a depth cap |
| Attribution in logs | The key, not the caller | The user, not the agent | Per agent and owner on every decision |
| Stopping one caller | Rotate for everyone | End the session | Revoke or rotate one agent |
| Human sign-off | Build it yourself | The user is already present | requireApproval constraint |

- [MCP OAuth 2.1 server](https://theauth.dev/mcp-oauth/)
- [Human auth](https://theauth.dev/human-auth/)
- [Security](https://theauth.dev/security/)
- [Agents on the homepage](https://theauth.dev/#agents)

[DPoP, CIBA and device flow](https://theauth.dev/agent-oauth/) [Delegated authorization for multi-agent systems](https://theauth.dev/use-cases/multi-agent/) [Auth0 alternative for agents](https://theauth.dev/compare/auth0/)
