Issue, rotate, revoke, and audit AgentIdentity tokens. Scoped permissions, parent/child delegation, and per-agent rate limits in one API.
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().
const agent = await theauth.agent.create({ ownerId: user.id, name: 'code-reviewer', type: 'autonomous', permissions: [ { resource: 'mcp:github:*', actions: ['read'] }, ],});// agent.token is a ta_... bearer, shown once, hashed at restconsole.log(agent.token);
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
autonomous
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.
delegated
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.
service
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
const agent = await theauth.agent.create({ ownerId: 'user-123', name: 'github-reader', type: 'autonomous', permissions: [ { resource: 'mcp:github:*', actions: ['read'] }, ], expiresAt: new Date(Date.now() + 7 * 24 * 3_600_000), // optional, defaults to 24h from now metadata: { purpose: 'nightly PR review' },});console.log(agent.token); // ta_..., only shown here
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:
Authorization: Bearer ta_a3f8c2e1d4b5...
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, ...).
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.
const rotated = await theauth.agent.rotate(agentId);// rotated.token is the new plaintext token
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.
await theauth.agent.revoke(agentId);// All future authorize() calls return allowed: false// The agent's token is rejected immediately
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_:
const rotated = await auth.agent.rotate(agent.id);console.log(rotated.token); // ta_..., shown once
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.
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.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"theAuth","description":"Open-source auth for AI agents and humans. Agent identity, delegation, MCP OAuth 2.1, passkeys and SSO for TypeScript, Go and Python.","colors":{"primary":"#5f6600","light":"#eef35f","dark":"#4f5700"},"logo":{"light":"https://mintcdn.com/glincker/sN6aTYhmZH03W5q5/logo/wordmark-light.svg?fit=max\u0026auto=format\u0026n=sN6aTYhmZH03W5q5\u0026q=85\u0026s=9f06802deef022182bb2153d27ed6a4b","dark":"https://mintcdn.com/glincker/sN6aTYhmZH03W5q5/logo/wordmark-dark.svg?fit=max\u0026auto=format\u0026n=sN6aTYhmZH03W5q5\u0026q=85\u0026s=92b365fb88100a30331a53917b2589bf","href":"https://theauth.dev"},"favicon":{"light":"https://mintcdn.com/glincker/sN6aTYhmZH03W5q5/favicon.svg?fit=max\u0026auto=format\u0026n=sN6aTYhmZH03W5q5\u0026q=85\u0026s=15cf4fe3b096301039ae4bba4b11c339","dark":"https://mintcdn.com/glincker/sN6aTYhmZH03W5q5/favicon.svg?fit=max\u0026auto=format\u0026n=sN6aTYhmZH03W5q5\u0026q=85\u0026s=15cf4fe3b096301039ae4bba4b11c339"},"appearance":{"default":"dark","strict":false},"background":{"color":{"light":"#ffffff","dark":"#000000"}},"navbar":{"links":[{"icon":"globe","href":"https://theauth.dev","label":"Website"},{"icon":"clock-rotate-left","href":"https://github.com/glincker/theauth/releases","label":"Changelog"},{"icon":"github","href":"https://github.com/glincker/theauth","label":"GitHub"}],"primary":{"type":"button","label":"Get started","href":"/quickstart"}},"footer":{"socials":{"github":"https://github.com/glincker/theauth","x":"https://x.com/thegdsks","website":"https://theauth.dev"}},"search":{"prompt":"Search docs, agents, SDKs, standards"},"seo":{"metatags":{"og:site_name":"theAuth","og:type":"website","og:image":"https://docs.theauth.dev/og-logo.png","og:image:width":"1200","og:image:height":"630","twitter:card":"summary_large_image","twitter:image":"https://docs.theauth.dev/og-logo.png","twitter:site":"@thegdsks"},"indexing":"navigable"},"fonts":{"heading":{"family":"Inter","weight":300},"body":{"family":"Inter"}},"styling":{"codeblocks":"dark","latex":false},"errors":{"404":{"redirect":false,"title":"Page not found","description":"This page moved or never existed. Head to the [quickstart](/quickstart) or search above."}},"contextual":{"options":["copy","view","chatgpt","claude","cursor","mcp"],"display":"header"},"interaction":{"drilldown":true},"metadata":{"timestamp":true},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"glincker","hasAudioNarration":false,"actualSubdomain":"glincker","customDomains":["docs.theauth.dev"],"gitSource":{"type":"github","owner":"glincker","repo":"theauth","deployBranch":"main","contentDirectory":"docs","isPrivate":false,"mountPath":"","label":""},"feedback":{"thumbs":true,"edits":true,"issues":true},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6ae6c6da8e7709423eee49b5","clientVersion":"0.0.4227","searchFilterCounts":[{"language":"default","tag":"Authentication","count":71},{"language":"default","tag":"Go","count":68},{"language":"default","tag":"Agents","count":51},{"language":"default","tag":"Platform","count":47},{"language":"default","tag":"OAuth providers","count":43},{"language":"default","tag":"Guides","count":33},{"language":"default","tag":"Advanced","count":27},{"language":"default","tag":"Get started","count":24},{"language":"default","tag":"Controls","count":20},{"language":"default","tag":"Framework adapters","count":18}],"searchSettings":{"showContentSnippets":true}},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"privacy":{"consentBanner":{"enabled":true}},"googleFontsInlined":false},"customCss":[{"filePath":"style.css","content":"@font-face{font-family:\"JetBrains Mono\";src:url(\"/fonts/jetbrains-mono-var.woff2\") format(\"woff2\");font-weight:100 800;font-display:swap}:root{--ta-live: #eef35f;--ta-violet: #b6abff;--ta-teal: #00cbaa;--ta-mono: \"JetBrains Mono\", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;--ta-r: 12px;--ta-face: #0e0f11;--ta-face-2: #141617;--ta-text: #cfcfd3;--ta-link: #b6abff;--ta-line: rgba(255, 255, 255, 0.08);--ta-ring: linear-gradient(180deg, rgba(255, 255, 255, 0.18), rgba(255, 255, 255, 0.04) 40%, rgba(255, 255, 255, 0.06));--ta-ring-hot: linear-gradient(180deg, rgba(238, 243, 95, 0.55), rgba(238, 243, 95, 0.12) 45%, rgba(238, 243, 95, 0.2));--ta-sheen: linear-gradient(180deg, rgba(255, 255, 255, 0.035), rgba(255, 255, 255, 0));--ta-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.07), 0 1px 1px rgba(0, 0, 0, 0.5), 0 8px 16px -4px rgba(0, 0, 0, 0.55), 0 24px 48px -12px rgba(0, 0, 0, 0.65);--ta-glow-op: 1;--ta-grain: url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='220' height='220'%3E%3Cfilter id='n' x='0' y='0' width='100%25' height='100%25'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='.9' numOctaves='2' stitchTiles='stitch'/%3E%3CfeColorMatrix values='0 0 0 0 1 0 0 0 0 1 0 0 0 0 1 9 0 0 0 -4.3'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E\")}html:not(.dark){--ta-face: #ffffff;--ta-face-2: #f6f6f7;--ta-text: #3a3d40;--ta-link: #5b4bc4;--ta-line: rgba(14, 15, 17, 0.1);--ta-ring: linear-gradient(180deg, rgba(14, 15, 17, 0.2), rgba(14, 15, 17, 0.08) 40%, rgba(14, 15, 17, 0.1));--ta-ring-hot: linear-gradient(180deg, rgba(95, 102, 0, 0.6), rgba(95, 102, 0, 0.18) 45%, rgba(95, 102, 0, 0.26));--ta-sheen: linear-gradient(180deg, rgba(255, 255, 255, 0.9), rgba(255, 255, 255, 0));--ta-shadow: 0 1px 1px rgba(14, 15, 17, 0.06), 0 8px 16px -6px rgba(14, 15, 17, 0.1);--ta-glow-op: 0.35}html.dark body{background-color:#000}body{position:relative;font-feature-settings:\"cv11\", \"ss03\";-webkit-font-smoothing:antialiased}body::before,body::after{content:\"\";position:absolute;inset:0 0 auto 0;height:440px;z-index:-1;pointer-events:none;background:radial-gradient(54% 92% at 50% 0%, rgba(182, 171, 255, 0.5), transparent 72%),\n radial-gradient(38% 78% at 10% 0%, rgba(0, 203, 170, 0.42), transparent 72%),\n radial-gradient(36% 70% at 92% 0%, rgba(238, 243, 95, 0.34), transparent 72%)}body::before{opacity:calc(0.4 * var(--ta-glow-op))}body::after{opacity:calc(0.9 * var(--ta-glow-op));filter:saturate(1.2) brightness(1.25);-webkit-mask-image:var(--ta-grain), linear-gradient(to bottom, #000 0%, transparent 88%);-webkit-mask-size:220px 220px, 100% 100%;-webkit-mask-composite:source-in;mask-image:var(--ta-grain), linear-gradient(to bottom, #000 0%, transparent 88%);mask-size:220px 220px, 100% 100%;mask-composite:intersect}html{isolation:isolate}#content-area,#content-container{color:var(--ta-text)}#page-title{font-weight:300;letter-spacing:-0.03em;line-height:1.08;text-wrap:balance}#content-area h2{font-weight:300;letter-spacing:-0.025em}#content-area h3,#content-area h4{font-weight:500;letter-spacing:-0.02em}#header p,#content-area p{text-wrap:pretty}#header>div>div:first-child:not(:has(h1)){font-family:var(--ta-mono);font-size:0.75rem;letter-spacing:0.08em;text-transform:uppercase;color:#8d8d96}#content-area a:not(.card):not([data-component-part]){color:var(--ta-link)}#content-area a[href]:not(.card){text-decoration-color:color-mix(in srgb, var(--ta-link) 40%, transparent)}#content-area a[href]:not(.card):hover{text-decoration-color:currentColor}code,pre,kbd,samp{font-family:var(--ta-mono)!important;font-feature-settings:\"calt\" 0}#content-area :not(pre)>code{background:var(--ta-face-2);border:1px solid var(--ta-line);border-radius:6px;padding:0.1em 0.4em;font-size:0.875em;color:inherit}html.dark #content-area :not(pre)>code{color:#e4e4e7}.code-block{border-radius:var(--ta-r);border:1px solid transparent;box-shadow:var(--ta-shadow);background:var(--ta-sheen) padding-box, linear-gradient(#08090a, #08090a) padding-box, var(--ta-ring) border-box}.code-block-background,.code-block>div{border-radius:var(--ta-r);background-color:transparent}.code-block [data-component-part=\"code-block-root\"],.code-block pre{background:transparent}.code-block code{font-size:0.8125rem;line-height:1.7}.card,.accordion,.accordion-group,.callout{border:1px solid transparent;border-radius:var(--ta-r);box-shadow:var(--ta-shadow);background:var(--ta-sheen) padding-box, linear-gradient(var(--ta-face), var(--ta-face)) padding-box, var(--ta-ring) border-box}.card{transition:box-shadow 0.2s, transform 0.2s}.card:hover{transform:translateY(-1px)}html.dark .card:hover{border-color:rgba(238, 243, 95, 0.45)}.card [data-component-part=\"card-title\"]{font-weight:500;letter-spacing:-0.01em}.card [data-component-part=\"card-icon\"]{color:var(--ta-live)}html:not(.dark) .card [data-component-part=\"card-icon\"]{color:#5f6600}.accordion{margin-bottom:0.75rem;overflow:hidden}.accordion-group{overflow:hidden}.callout{padding:1rem 1.25rem}.callout[class*=\"border-yellow\"],.callout[class*=\"border-green\"],.callout[class*=\"border-blue\"],.callout[class*=\"border-red\"],.callout[class*=\"border-sky\"]{background:var(--ta-sheen) padding-box, linear-gradient(var(--ta-face), var(--ta-face)) padding-box, var(--ta-ring) border-box}@media (prefers-reduced-motion: reduce){.card{transition:none}.card:hover{transform:none}}#content-area table{border-collapse:separate;border-spacing:0;border:1px solid var(--ta-line);border-radius:var(--ta-r);overflow:hidden;box-shadow:var(--ta-shadow)}#content-area thead th{font-family:var(--ta-mono);font-size:0.75rem;font-weight:500;letter-spacing:0.06em;text-transform:uppercase;color:#8d8d96;background:var(--ta-face-2)}#content-area tbody td,#content-area thead th{border-bottom:1px solid var(--ta-line)}#content-area tbody tr:last-child td{border-bottom:0}#navbar>div.absolute,#navbar>div>div.absolute{background:color-mix(in srgb, var(--ta-face) 55%, transparent);border-bottom-color:var(--ta-line);backdrop-filter:none}#sidebar .sticky.pointer-events-none{background:none}#navbar .nav-tabs-item[data-active=\"true\"]{color:var(--ta-live)}html:not(.dark) #navbar .nav-tabs-item[data-active=\"true\"]{color:#5f6600}#navbar .nav-tabs-item[data-active=\"true\"]>div,#navbar .nav-tabs-item[data-active=\"true\"]::after{background:var(--ta-live)}html:not(.dark) #navbar .nav-tabs-item[data-active=\"true\"]>div,html:not(.dark) #navbar .nav-tabs-item[data-active=\"true\"]::after{background:#5f6600}#topbar-cta-button a>span.absolute{border-radius:50px;background:var(--ta-live);border:1px solid rgba(255, 255, 255, 0.35);box-shadow:inset 0 1px 0 rgba(255, 255, 255, 0.55), inset 0 -2px 0 rgba(0, 0, 0, 0.18), 0 6px 14px -6px rgba(238, 243, 95, 0.45)}#topbar-cta-button a{padding-left:1rem;padding-right:0.75rem}#topbar-cta-button a .text-white,#topbar-cta-button a svg{color:#000!important}html:not(.dark) #topbar-cta-button a>span.absolute{background:#0e0f11;border-color:transparent;box-shadow:0 1px 1px rgba(14, 15, 17, 0.3)}html:not(.dark) #topbar-cta-button a .text-white,html:not(.dark) #topbar-cta-button a svg{color:#eef35f!important}#search-bar-entry{border-radius:50px;border:1px solid transparent;box-shadow:var(--ta-shadow);background:var(--ta-sheen) padding-box, linear-gradient(var(--ta-face-2), var(--ta-face-2)) padding-box, var(--ta-ring) border-box}#search-bar-entry:hover{background:var(--ta-sheen) padding-box, linear-gradient(var(--ta-face-2), var(--ta-face-2)) padding-box, var(--ta-ring-hot) border-box}#sidebar .sidebar-group-header{font-family:var(--ta-mono);font-size:0.6875rem;letter-spacing:0.08em;text-transform:uppercase;font-weight:500;color:#8d8d96}#sidebar a[aria-current=\"page\"]{border-radius:50px;color:var(--ta-live);background:rgba(238, 243, 95, 0.08);box-shadow:inset 0 0 0 1px rgba(238, 243, 95, 0.2)}html:not(.dark) #sidebar a[aria-current=\"page\"]{color:#4f5700;background:rgba(95, 102, 0, 0.09);box-shadow:inset 0 0 0 1px rgba(95, 102, 0, 0.25)}#sidebar a:not([aria-current=\"page\"]):hover{border-radius:50px}#table-of-contents a[data-active=\"true\"],#table-of-contents .toc-item[data-active=\"true\"]{color:var(--ta-live)}html:not(.dark) #table-of-contents a[data-active=\"true\"]{color:#5f6600}#sidebar img[src^=\"/brand-icons/\"],main img[src^=\"/brand-icons/\"]{width:1em;height:1em;display:inline-block;vertical-align:-0.125em;object-fit:contain}html.dark #sidebar img[src^=\"/brand-icons/\"]{filter:invert(1) brightness(0.9)}#footer{border-top:1px solid var(--ta-line)}"}]}
{"page":{"pagePath":"agents","slug":"/agents","pageMetadata":{"title":"Agent identity","description":"Issue, rotate, revoke, and audit AgentIdentity tokens. Scoped permissions, parent/child delegation, and per-agent rate limits in one API.","icon":"robot","href":"/agents"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Issue, rotate, revoke, and audit AgentIdentity tokens. Scoped permissions, parent/child delegation, and per-agent rate limits in one API.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,p:`p`,pre:`pre`,span:`span`,..._provideComponents(),...props.components},{Accordion,AccordionGroup,Card,CardGroup,CodeBlock,Columns,Frame,Heading,Info,OptimizedImage,ParamField,Step,Steps,Tip,Warning}=_components;if(!Accordion)_missingMdxReference(`Accordion`,true);if(!AccordionGroup)_missingMdxReference(`AccordionGroup`,true);if(!Card)_missingMdxReference(`Card`,true);if(!CardGroup)_missingMdxReference(`CardGroup`,true);if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Columns)_missingMdxReference(`Columns`,true);if(!Frame)_missingMdxReference(`Frame`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Info)_missingMdxReference(`Info`,true);if(!OptimizedImage)_missingMdxReference(`OptimizedImage`,true);if(!ParamField)_missingMdxReference(`ParamField`,true);if(!Step)_missingMdxReference(`Step`,true);if(!Steps)_missingMdxReference(`Steps`,true);if(!Tip)_missingMdxReference(`Tip`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsxs(Columns,{cols:2,children:[_jsxs(`div`,{children:[_jsxs(_components.p,{children:[`An `,_jsx(_components.code,{children:`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.`]}),_jsxs(_components.p,{children:[`Create one against an existing user ID, hand the token to the agent, and check every action through `,_jsx(_components.code,{children:`authorize()`}),`.`]})]}),_jsx(CodeBlock,{filename:``,numberOfLines:`11`,language:`typescript`,children:_jsx(_components.pre,{className:`shiki shiki-themes dark-plus dark-plus`,style:{backgroundColor:`#0B0C0E`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},language:`typescript`,children:_jsxs(_components.code,{language:`typescript`,numberOfLines:`11`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#569CD6`,\"--shiki-dark\":`#569CD6`},children:`const`}),_jsx(_components.span,{style:{color:`#4FC1FF`,\"--shiki-dark\":`#4FC1FF`},children:` agent`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` = `}),_jsx(_components.span,{style:{color:`#C586C0`,\"--shiki-dark\":`#C586C0`},children:`await`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` theauth`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`agent`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#DCDCAA`,\"--shiki-dark\":`#DCDCAA`},children:`create`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`({`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` ownerId:`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` user`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`id`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` name:`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:` 'code-reviewer'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` type:`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:` 'autonomous'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` permissions:`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` [`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` { `}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`resource:`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:` 'mcp:github:*'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`actions:`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` [`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:`'read'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`] },`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` ],`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`});`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6A9955`,\"--shiki-dark\":`#6A9955`},children:`// agent.token is a ta_... bearer, shown once, hashed at rest`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`console`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#DCDCAA`,\"--shiki-dark\":`#DCDCAA`},children:`log`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`agent`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`token`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`);`})]}),`\n`]})})})]}),`\n`,_jsx(Heading,{level:`2`,id:`anatomy`,children:`Anatomy`}),`\n`,_jsx(ParamField,{path:`id`,type:`string`,id:`param-id`,children:`Stable identifier (a UUID). Never changes.`}),`\n`,_jsxs(ParamField,{path:`token`,type:`string`,id:`param-token`,children:[`Bearer token with a `,_jsx(_components.code,{children:`ta_`}),` prefix (legacy `,_jsx(_components.code,{children:`kv_`}),` tokens are still accepted). Shown once at creation, then SHA-256 hashed. Rotate to replace.`]}),`\n`,_jsxs(ParamField,{path:`permissions`,type:`Permission[]`,id:`param-permissions`,children:[`What this agent is allowed to do. Evaluated at every `,_jsx(_components.code,{children:`authorize()`}),` call.`]}),`\n`,_jsx(ParamField,{path:`status`,type:`'active' | 'revoked' | 'expired'`,id:`param-status`,children:`Current state. Revocation is permanent.`}),`\n`,_jsxs(ParamField,{path:`ownerId`,type:`string`,id:`param-owner-id`,children:[`The user who owns this agent. Must match an existing row in `,_jsx(_components.code,{children:`theauth_users`}),` (foreign key). Create the row with `,_jsx(_components.code,{children:`theauth.user.create({ id, email })`}),`.`]}),`\n`,_jsx(ParamField,{path:`name`,type:`string`,id:`param-name`,children:`Human-readable label.`}),`\n`,_jsx(ParamField,{path:`type`,type:`'autonomous' | 'delegated' | 'service'`,id:`param-type`,children:`Determines how the agent acquires and uses permissions.`}),`\n`,_jsxs(ParamField,{path:`expiresAt`,type:`Date`,default:`now + agents.tokenExpiry (24h)`,id:`param-expires-at`,children:[`Optional at creation; when omitted it defaults to `,_jsx(_components.code,{children:`agents.tokenExpiry`}),` from now. Token validation (`,_jsx(_components.code,{children:`authorizeByToken`}),`) rejects an expired agent and flips its `,_jsx(_components.code,{children:`status`}),` to `,_jsx(_components.code,{children:`expired`}),`. `,_jsx(_components.code,{children:`authorize(agentId)`}),` also compares `,_jsx(_components.code,{children:`expiresAt`}),` to the clock, so an elapsed agent is denied with code `,_jsx(_components.code,{children:`agent_expired`}),` (and an audit row) even before its stored `,_jsx(_components.code,{children:`status`}),` flips.`]}),`\n`,_jsx(ParamField,{path:`metadata`,type:`Record\u003cstring, unknown>`,default:`{}`,id:`param-metadata`,children:`Arbitrary key/value pairs for your own use.`}),`\n`,_jsx(Heading,{level:`2`,id:`agent-types`,children:`Agent types`}),`\n`,_jsxs(AccordionGroup,{children:[_jsx(Accordion,{title:`autonomous`,icon:`robot`,id:`autonomous`,children:_jsx(_components.p,{children:`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.`})}),_jsx(Accordion,{title:`delegated`,icon:`link`,id:`delegated`,children:_jsx(_components.p,{children:`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.`})}),_jsx(Accordion,{title:`service`,icon:`server`,id:`service`,children:_jsx(_components.p,{children:`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.`})})]}),`\n`,_jsx(Heading,{level:`2`,id:`lifecycle`,children:`Lifecycle`}),`\n`,_jsxs(Steps,{children:[_jsxs(Step,{title:`Create`,children:[_jsx(CodeBlock,{filename:``,numberOfLines:`12`,language:`typescript`,children:_jsx(_components.pre,{className:`shiki shiki-themes dark-plus dark-plus`,style:{backgroundColor:`#0B0C0E`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},language:`typescript`,children:_jsxs(_components.code,{language:`typescript`,numberOfLines:`12`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#569CD6`,\"--shiki-dark\":`#569CD6`},children:`const`}),_jsx(_components.span,{style:{color:`#4FC1FF`,\"--shiki-dark\":`#4FC1FF`},children:` agent`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` = `}),_jsx(_components.span,{style:{color:`#C586C0`,\"--shiki-dark\":`#C586C0`},children:`await`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` theauth`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`agent`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#DCDCAA`,\"--shiki-dark\":`#DCDCAA`},children:`create`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`({`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` ownerId:`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:` 'user-123'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` name:`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:` 'github-reader'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` type:`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:` 'autonomous'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` permissions:`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` [`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` { `}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`resource:`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:` 'mcp:github:*'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`actions:`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` [`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:`'read'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`] },`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` ],`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` expiresAt:`}),_jsx(_components.span,{style:{color:`#569CD6`,\"--shiki-dark\":`#569CD6`},children:` new`}),_jsx(_components.span,{style:{color:`#DCDCAA`,\"--shiki-dark\":`#DCDCAA`},children:` Date`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`Date`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#DCDCAA`,\"--shiki-dark\":`#DCDCAA`},children:`now`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`() + `}),_jsx(_components.span,{style:{color:`#B5CEA8`,\"--shiki-dark\":`#B5CEA8`},children:`7`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` * `}),_jsx(_components.span,{style:{color:`#B5CEA8`,\"--shiki-dark\":`#B5CEA8`},children:`24`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` * `}),_jsx(_components.span,{style:{color:`#B5CEA8`,\"--shiki-dark\":`#B5CEA8`},children:`3_600_000`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`), `}),_jsx(_components.span,{style:{color:`#6A9955`,\"--shiki-dark\":`#6A9955`},children:`// optional, defaults to 24h from now`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` metadata:`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` { `}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`purpose:`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:` 'nightly PR review'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` },`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`});`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`console`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#DCDCAA`,\"--shiki-dark\":`#DCDCAA`},children:`log`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`agent`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`token`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`); `}),_jsx(_components.span,{style:{color:`#6A9955`,\"--shiki-dark\":`#6A9955`},children:`// ta_..., only shown here`})]}),`\n`]})})}),_jsx(Warning,{children:_jsx(_components.p,{children:`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.`})})]}),_jsxs(Step,{title:`Authenticate`,children:[_jsxs(_components.p,{children:[`Tokens use the `,_jsx(_components.code,{children:`ta_`}),` prefix followed by 32 random bytes encoded as base64url (43 characters, 46 in total). Pass as a Bearer credential:`]}),_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`http`,children:_jsx(_components.pre,{className:`shiki shiki-themes dark-plus dark-plus`,style:{backgroundColor:`#0B0C0E`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},language:`http`,children:_jsxs(_components.code,{language:`http`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#569CD6`,\"--shiki-dark\":`#569CD6`},children:`Authorization:`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:` Bearer ta_a3f8c2e1d4b5...`})]}),`\n`]})})}),_jsx(Tip,{children:_jsx(_components.p,{children:`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.`})})]}),_jsxs(Step,{title:`Authorize`,children:[_jsxs(_components.p,{children:[`When a caller only has the raw token, use `,_jsx(_components.code,{children:`authorizeByToken`}),` in your HTTP middleware:`]}),_jsx(CodeBlock,{filename:``,numberOfLines:`11`,language:`typescript`,children:_jsx(_components.pre,{className:`shiki shiki-themes dark-plus dark-plus`,style:{backgroundColor:`#0B0C0E`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},language:`typescript`,children:_jsxs(_components.code,{language:`typescript`,numberOfLines:`11`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#569CD6`,\"--shiki-dark\":`#569CD6`},children:`const`}),_jsx(_components.span,{style:{color:`#4FC1FF`,\"--shiki-dark\":`#4FC1FF`},children:` token`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` = `}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`request`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`headers`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#DCDCAA`,\"--shiki-dark\":`#DCDCAA`},children:`get`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:`'Authorization'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`)?.`}),_jsx(_components.span,{style:{color:`#DCDCAA`,\"--shiki-dark\":`#DCDCAA`},children:`replace`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:`'Bearer '`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:`''`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`);`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#C586C0`,\"--shiki-dark\":`#C586C0`},children:`if`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` (!`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`token`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`) `}),_jsx(_components.span,{style:{color:`#C586C0`,\"--shiki-dark\":`#C586C0`},children:`return`}),_jsx(_components.span,{style:{color:`#569CD6`,\"--shiki-dark\":`#569CD6`},children:` new`}),_jsx(_components.span,{style:{color:`#DCDCAA`,\"--shiki-dark\":`#DCDCAA`},children:` Response`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:`'Unauthorized'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`, { `}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`status:`}),_jsx(_components.span,{style:{color:`#B5CEA8`,\"--shiki-dark\":`#B5CEA8`},children:` 401`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` });`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#569CD6`,\"--shiki-dark\":`#569CD6`},children:`const`}),_jsx(_components.span,{style:{color:`#4FC1FF`,\"--shiki-dark\":`#4FC1FF`},children:` result`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` = `}),_jsx(_components.span,{style:{color:`#C586C0`,\"--shiki-dark\":`#C586C0`},children:`await`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` theauth`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#DCDCAA`,\"--shiki-dark\":`#DCDCAA`},children:`authorizeByToken`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`token`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`, {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` action:`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:` 'read'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` resource:`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:` 'mcp:github:repos'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`});`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#C586C0`,\"--shiki-dark\":`#C586C0`},children:`if`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` (!`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`result`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`allowed`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`) {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#C586C0`,\"--shiki-dark\":`#C586C0`},children:` return`}),_jsx(_components.span,{style:{color:`#569CD6`,\"--shiki-dark\":`#569CD6`},children:` new`}),_jsx(_components.span,{style:{color:`#DCDCAA`,\"--shiki-dark\":`#DCDCAA`},children:` Response`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`result`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`reason`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` ?? `}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:`'Forbidden'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`, { `}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`status:`}),_jsx(_components.span,{style:{color:`#B5CEA8`,\"--shiki-dark\":`#B5CEA8`},children:` 403`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` });`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`}`})}),`\n`]})})}),_jsxs(_components.p,{children:[`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 `,_jsx(_components.code,{children:`authorize(agentId, ...)`}),`.`]}),_jsx(Frame,{caption:`An authorize() call checks permissions, writes the audit record and returns allowed with an auditId.`,children:_jsx(OptimizedImage,{src:`https://mintcdn.com/glincker/HempoE2qsVe2kr4N/images/diagrams/authorize-flow.png?fit=max\u0026auto=format\u0026n=HempoE2qsVe2kr4N\u0026q=85\u0026s=78a458dec1b77b7db72081af5fa60a4b`,alt:`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.`,\"data-og-width\":`1864`,width:`1864`,\"data-og-height\":`852`,height:`852`,\"data-path\":`images/diagrams/authorize-flow.png`,\"data-optimize\":`true`,\"data-opv\":`3`,srcset:`https://mintcdn.com/glincker/HempoE2qsVe2kr4N/images/diagrams/authorize-flow.png?w=280\u0026fit=max\u0026auto=format\u0026n=HempoE2qsVe2kr4N\u0026q=85\u0026s=b2692a065b28b5131662f2b757f2a1d1 280w, https://mintcdn.com/glincker/HempoE2qsVe2kr4N/images/diagrams/authorize-flow.png?w=560\u0026fit=max\u0026auto=format\u0026n=HempoE2qsVe2kr4N\u0026q=85\u0026s=4e461a46c1166477845d98d4b21018bb 560w, https://mintcdn.com/glincker/HempoE2qsVe2kr4N/images/diagrams/authorize-flow.png?w=840\u0026fit=max\u0026auto=format\u0026n=HempoE2qsVe2kr4N\u0026q=85\u0026s=7a8a09e635d4ee25bd2edbd6fd6884ab 840w, https://mintcdn.com/glincker/HempoE2qsVe2kr4N/images/diagrams/authorize-flow.png?w=1100\u0026fit=max\u0026auto=format\u0026n=HempoE2qsVe2kr4N\u0026q=85\u0026s=52fb6ab90277f2a6bb1037180fc18d26 1100w, https://mintcdn.com/glincker/HempoE2qsVe2kr4N/images/diagrams/authorize-flow.png?w=1650\u0026fit=max\u0026auto=format\u0026n=HempoE2qsVe2kr4N\u0026q=85\u0026s=200b73737d91d9c3b4275fb58d1c5466 1650w, https://mintcdn.com/glincker/HempoE2qsVe2kr4N/images/diagrams/authorize-flow.png?w=2500\u0026fit=max\u0026auto=format\u0026n=HempoE2qsVe2kr4N\u0026q=85\u0026s=01f2450e442821ba7e59a6c39d8903d6 2500w`})})]}),_jsxs(Step,{title:`Rotate`,children:[_jsx(_components.p,{children:`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.`}),_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`typescript`,children:_jsx(_components.pre,{className:`shiki shiki-themes dark-plus dark-plus`,style:{backgroundColor:`#0B0C0E`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},language:`typescript`,children:_jsxs(_components.code,{language:`typescript`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#569CD6`,\"--shiki-dark\":`#569CD6`},children:`const`}),_jsx(_components.span,{style:{color:`#4FC1FF`,\"--shiki-dark\":`#4FC1FF`},children:` rotated`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` = `}),_jsx(_components.span,{style:{color:`#C586C0`,\"--shiki-dark\":`#C586C0`},children:`await`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` theauth`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`agent`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#DCDCAA`,\"--shiki-dark\":`#DCDCAA`},children:`rotate`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`agentId`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`);`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6A9955`,\"--shiki-dark\":`#6A9955`},children:`// rotated.token is the new plaintext token`})}),`\n`]})})}),_jsx(_components.p,{children:`Rotate on a schedule, or any time you suspect a token has been exposed.`})]}),_jsxs(Step,{title:`Update or list`,children:[_jsx(_components.p,{children:`Permission updates take effect immediately. In-flight requests that already passed authorization are not affected.`}),_jsx(CodeBlock,{filename:``,numberOfLines:`10`,language:`typescript`,children:_jsx(_components.pre,{className:`shiki shiki-themes dark-plus dark-plus`,style:{backgroundColor:`#0B0C0E`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},language:`typescript`,children:_jsxs(_components.code,{language:`typescript`,numberOfLines:`10`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#C586C0`,\"--shiki-dark\":`#C586C0`},children:`await`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` theauth`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`agent`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#DCDCAA`,\"--shiki-dark\":`#DCDCAA`},children:`update`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`agentId`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`, {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` name:`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:` 'github-reader-v2'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` permissions:`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` [{ `}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`resource:`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:` 'mcp:github:*'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`actions:`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` [`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:`'read'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:`'comment'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`] }],`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`});`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#569CD6`,\"--shiki-dark\":`#569CD6`},children:`const`}),_jsx(_components.span,{style:{color:`#4FC1FF`,\"--shiki-dark\":`#4FC1FF`},children:` active`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` = `}),_jsx(_components.span,{style:{color:`#C586C0`,\"--shiki-dark\":`#C586C0`},children:`await`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` theauth`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`agent`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#DCDCAA`,\"--shiki-dark\":`#DCDCAA`},children:`list`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`({`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` userId:`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:` 'user-123'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` status:`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:` 'active'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` type:`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:` 'autonomous'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`});`})}),`\n`]})})})]}),_jsxs(Step,{title:`Revoke`,children:[_jsx(CodeBlock,{filename:``,numberOfLines:`3`,language:`typescript`,children:_jsx(_components.pre,{className:`shiki shiki-themes dark-plus dark-plus`,style:{backgroundColor:`#0B0C0E`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},language:`typescript`,children:_jsxs(_components.code,{language:`typescript`,numberOfLines:`3`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#C586C0`,\"--shiki-dark\":`#C586C0`},children:`await`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` theauth`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`agent`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#DCDCAA`,\"--shiki-dark\":`#DCDCAA`},children:`revoke`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`agentId`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`);`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6A9955`,\"--shiki-dark\":`#6A9955`},children:`// All future authorize() calls return allowed: false`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6A9955`,\"--shiki-dark\":`#6A9955`},children:`// The agent's token is rejected immediately`})}),`\n`]})})}),_jsxs(_components.p,{children:[`Each attempt by a revoked or expired agent is still written to the audit log as a denied row with the reason `,_jsx(_components.code,{children:`agent_revoked`}),` or `,_jsx(_components.code,{children:`agent_expired`}),`. See `,_jsx(_components.a,{href:`/audit-trail#what-gets-recorded`,children:`what gets recorded`}),`. `,_jsx(_components.code,{children:`policy.evaluate()`}),` denies a revoked, suspended or expired agent with `,_jsx(_components.code,{children:`POLICY_AGENT_INACTIVE`}),`.`]}),_jsxs(_components.p,{children:[`In the TypeScript package, `,_jsx(_components.code,{children:`agent.revoke()`}),` also revokes every active delegation chain the agent gave or received, and the chains downstream of them. The call returns `,_jsx(_components.code,{children:`{ revokedDelegations }`}),` with the chain ids, writes one `,_jsx(_components.code,{children:`agent.cascade.revoked`}),` audit row, and fires `,_jsx(_components.code,{children:`onAgentRevoke`}),`.`]}),_jsx(Warning,{children:_jsx(_components.p,{children:`Revocation is permanent. There is no un-revoke. To restore access, create a new agent.`})})]})]}),`\n`,_jsx(Heading,{level:`2`,id:`token-format`,children:`Token format`}),`\n`,_jsxs(_components.p,{children:[`New agent tokens look like `,_jsx(_components.code,{children:`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.`]}),`\n`,_jsxs(_components.p,{children:[`Tokens issued by earlier releases start with `,_jsx(_components.code,{children:`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 `,_jsx(_components.code,{children:`kv_`}),`.`]}),`\n`,_jsxs(_components.p,{children:[`To move an agent off a legacy token, rotate it. The old token stops working at once and the new one starts with `,_jsx(_components.code,{children:`ta_`}),`:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`typescript`,children:_jsx(_components.pre,{className:`shiki shiki-themes dark-plus dark-plus`,style:{backgroundColor:`#0B0C0E`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},language:`typescript`,children:_jsxs(_components.code,{language:`typescript`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#569CD6`,\"--shiki-dark\":`#569CD6`},children:`const`}),_jsx(_components.span,{style:{color:`#4FC1FF`,\"--shiki-dark\":`#4FC1FF`},children:` rotated`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` = `}),_jsx(_components.span,{style:{color:`#C586C0`,\"--shiki-dark\":`#C586C0`},children:`await`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` auth`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`agent`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#DCDCAA`,\"--shiki-dark\":`#DCDCAA`},children:`rotate`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`agent`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`id`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`);`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`console`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#DCDCAA`,\"--shiki-dark\":`#DCDCAA`},children:`log`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`rotated`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`token`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`); `}),_jsx(_components.span,{style:{color:`#6A9955`,\"--shiki-dark\":`#6A9955`},children:`// ta_..., shown once`})]}),`\n`]})})}),`\n`,_jsx(Heading,{level:`3`,id:`secret-scanning`,children:`Secret scanning`}),`\n`,_jsx(_components.p,{children:`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.`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes dark-plus dark-plus`,style:{backgroundColor:`#0B0C0E`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`2`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`\\\\b(?:ta|kv)_[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]\\\\b`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsx(_components.p,{children:`A gitleaks rule:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`5`,language:`toml`,children:_jsx(_components.pre,{className:`shiki shiki-themes dark-plus dark-plus`,style:{backgroundColor:`#0B0C0E`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},language:`toml`,children:_jsxs(_components.code,{language:`toml`,numberOfLines:`5`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`[[rules]]`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`id`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` = `}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:`\"theauth-agent-token\"`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`description`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` = `}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:`\"theAuth agent token\"`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`regex`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` = `}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:`'''\\\\b(?:ta|kv)_[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]\\\\b'''`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`keywords`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` = [`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:`\"ta_\"`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:`\"kv_\"`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`]`})]}),`\n`]})})}),`\n`,_jsx(Heading,{level:`2`,id:`limits`,children:`Limits`}),`\n`,_jsx(_components.p,{children:`The default is 10 active agents per user. Raise at initialization:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`7`,language:`typescript`,children:_jsx(_components.pre,{className:`shiki shiki-themes dark-plus dark-plus`,style:{backgroundColor:`#0B0C0E`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},language:`typescript`,children:_jsxs(_components.code,{language:`typescript`,numberOfLines:`7`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#569CD6`,\"--shiki-dark\":`#569CD6`},children:`const`}),_jsx(_components.span,{style:{color:`#4FC1FF`,\"--shiki-dark\":`#4FC1FF`},children:` theauth`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` = `}),_jsx(_components.span,{style:{color:`#C586C0`,\"--shiki-dark\":`#C586C0`},children:`await`}),_jsx(_components.span,{style:{color:`#DCDCAA`,\"--shiki-dark\":`#DCDCAA`},children:` createTheAuth`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`({`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` database:`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` { `}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`provider:`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:` 'sqlite-native'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:`url:`}),_jsx(_components.span,{style:{color:`#CE9178`,\"--shiki-dark\":`#CE9178`},children:` 'theauth.db'`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` },`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` agents:`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` {`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` enabled:`}),_jsx(_components.span,{style:{color:`#569CD6`,\"--shiki-dark\":`#569CD6`},children:` true`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#9CDCFE`,\"--shiki-dark\":`#9CDCFE`},children:` maxPerUser:`}),_jsx(_components.span,{style:{color:`#B5CEA8`,\"--shiki-dark\":`#B5CEA8`},children:` 50`}),_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:` },`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#D4D4D4`,\"--shiki-dark\":`#D4D4D4`},children:`});`})}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`The cap counts active agents. Creating one past it throws a plain `,_jsx(_components.code,{children:`Error`}),` with the message `,_jsx(_components.code,{children:`User \u003cid> has reached the maximum of \u003cn> active agents.`}),` (there is no dedicated error code, and the REST endpoint reports it as `,_jsx(_components.code,{children:`500 INTERNAL_ERROR`}),`).`]}),`\n`,_jsx(Heading,{level:`2`,id:`what-agents-aren’t`,children:`What agents aren’t`}),`\n`,_jsx(Info,{children:_jsx(_components.p,{children:`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.`})}),`\n`,_jsx(Heading,{level:`2`,id:`next-steps`,children:`Next steps`}),`\n`,_jsxs(CardGroup,{cols:2,children:[_jsx(Card,{title:`Permission engine`,icon:`shield-halved`,href:`/permissions`,children:_jsx(_components.p,{children:`Define what agents can and cannot do.`})}),_jsx(Card,{title:`Delegation chains`,icon:`link`,href:`/delegation`,children:_jsx(_components.p,{children:`Let agents delegate access to sub-agents.`})}),_jsx(Card,{title:`Ephemeral sessions`,icon:`stopwatch`,href:`/ephemeral-sessions`,children:_jsx(_components.p,{children:`Short-lived agents for one-off tasks.`})}),_jsx(Card,{title:`Framework adapters`,icon:`puzzle-piece`,href:`/adapters`,children:_jsx(_components.p,{children:`Use agents in HTTP middleware.`})})]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"codeStyling":"dark","config":{},"pageMetadata":{"title":"Agent identity","description":"Issue, rotate, revoke, and audit AgentIdentity tokens. Scoped permissions, parent/child delegation, and per-agent rate limits in one API.","icon":"robot","href":"/agents"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Anatomy","slug":"anatomy","depth":2,"children":[]},{"title":"Agent types","slug":"agent-types","depth":2,"children":[]},{"title":"Lifecycle","slug":"lifecycle","depth":2,"children":[]},{"title":"Token format","slug":"token-format","depth":2,"children":[{"title":"Secret scanning","slug":"secret-scanning","depth":3,"children":[]}]},{"title":"Limits","slug":"limits","depth":2,"children":[]},{"title":"What agents aren’t","slug":"what-agents-aren’t","depth":2,"children":[]},{"title":"Next steps","slug":"next-steps","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"glincker","siteName":"theAuth","title":"Agent identity - theAuth","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-18T05:49:46.353Z","gitLastModified":"2026-10-18T05:49:19.000Z","originalFileLocation":"agents.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"dark\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Issue, rotate, revoke, and audit AgentIdentity tokens. Scoped permissions, parent/child delegation, and per-agent rate limits in one API.\">\u003cmeta data-mint-head name=\"application-name\" content=\"theAuth\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/glincker/MCvcDLGp1s98lfDL/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/glincker/MCvcDLGp1s98lfDL/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/glincker/MCvcDLGp1s98lfDL/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/glincker/MCvcDLGp1s98lfDL/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/glincker/MCvcDLGp1s98lfDL/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/glincker/MCvcDLGp1s98lfDL/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/glincker/MCvcDLGp1s98lfDL/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/glincker/MCvcDLGp1s98lfDL/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/glincker/MCvcDLGp1s98lfDL/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Agent identity - theAuth\">\u003cmeta data-mint-head property=\"og:description\" content=\"Issue, rotate, revoke, and audit AgentIdentity tokens. Scoped permissions, parent/child delegation, and per-agent rate limits in one API.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"theAuth\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.theauth.dev/agents\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://docs.theauth.dev/og-logo.png\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Agent identity - theAuth\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Issue, rotate, revoke, and audit AgentIdentity tokens. Scoped permissions, parent/child delegation, and per-agent rate limits in one API.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://docs.theauth.dev/og-logo.png\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/glincker/MCvcDLGp1s98lfDL/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"theAuth\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#5f6600\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.theauth.dev/agents\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/agents.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.theauth.dev/#organization\",\"name\":\"theAuth\",\"url\":\"https://docs.theauth.dev\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/glincker/sN6aTYhmZH03W5q5/logo/wordmark-light.svg?fit=max\u0026auto=format\u0026n=sN6aTYhmZH03W5q5\u0026q=85\u0026s=9f06802deef022182bb2153d27ed6a4b\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.theauth.dev#website\",\"name\":\"theAuth\",\"url\":\"https://docs.theauth.dev\",\"publisher\":{\"@id\":\"https://docs.theauth.dev/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.theauth.dev/agents#webpage\",\"url\":\"https://docs.theauth.dev/agents\",\"name\":\"Agent identity\",\"description\":\"Issue, rotate, revoke, and audit AgentIdentity tokens. Scoped permissions, parent/child delegation, and per-agent rate limits in one API.\",\"dateModified\":\"2026-10-18T05:49:19.000Z\",\"isPartOf\":{\"@id\":\"https://docs.theauth.dev#website\"},\"breadcrumb\":{\"@id\":\"https://docs.theauth.dev/agents#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.theauth.dev/agents#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"theAuth\",\"item\":\"https://docs.theauth.dev\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Agent identity\",\"item\":\"https://docs.theauth.dev/agents\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.theauth.dev/agents#article\",\"headline\":\"Agent identity\",\"name\":\"Agent identity\",\"description\":\"Issue, rotate, revoke, and audit AgentIdentity tokens. Scoped permissions, parent/child delegation, and per-agent rate limits in one API.\",\"url\":\"https://docs.theauth.dev/agents\",\"mainEntityOfPage\":{\"@id\":\"https://docs.theauth.dev/agents#webpage\"},\"image\":\"https://docs.theauth.dev/og-logo.png\",\"dateModified\":\"2026-10-18T05:49:19.000Z\",\"publisher\":{\"@id\":\"https://docs.theauth.dev/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.theauth.dev#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"theAuth\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"theAuth\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/agents.md","siteName":"theAuth","nav":{"global":null,"tabs":[{"tab":"Get started","icon":"rocket","pages":[{"title":"Get started","href":""}]},{"tab":"Authentication","icon":"key","pages":[{"title":"Authentication","href":"/auth"}]},{"tab":"Agents","icon":"robot","groups":[{"group":"Identity","icon":"fingerprint","pages":[{"title":"Agent identity","icon":"robot","href":"/agents"},{"title":"Ephemeral sessions","description":"Short-lived, auto-expiring agent credentials for single-task computer-use agents.","icon":"stopwatch","href":"/ephemeral-sessions"},{"title":"Delegation chains","icon":"link","href":"/delegation"},{"title":"IoT devices","icon":"microchip","href":"/iot-devices"},{"title":"SPIFFE workload identity","icon":"id-card","href":"/spiffe"},{"title":"Device conformance kit","icon":"vial","href":"/device-conformance-kit"},{"title":"Token vault","icon":"vault","href":"/token-vault"}]},{"group":"Authorization","icon":"shield-halved","pages":[{"title":"Permission engine","icon":"user-shield","href":"/permissions"},{"title":"Policy engine","icon":"shield-halved","href":"/policy-engine"},{"title":"Policy testing","icon":"flask","href":"/policy-testing"},{"title":"Relationship-based access control","icon":"network-wired","href":"/rebac"},{"title":"Policy templates","href":"/policies/templates"}]},{"group":"Observability","icon":"chart-line","pages":[{"title":"AI agent identity and accountability","icon":"scale-balanced","href":"/accountability"},{"title":"Agent RACI template","icon":"table","href":"/accountability-raci-template"},{"title":"Audit trail","icon":"scroll","href":"/audit"},{"title":"Tamper-evident audit trail","icon":"link","href":"/audit-trail"},{"title":"Input provenance","icon":"route","href":"/input-provenance"},{"title":"Audit receipts and chain vectors","icon":"file-certificate","href":"/audit-receipts"},{"title":"Audit checkpoints and receipts","icon":"stamp","href":"/audit-checkpoints"},{"title":"Observability","icon":"activity","href":"/observability"},{"title":"Database hooks","icon":"webhook","href":"/database-hooks"},{"title":"ID generation","icon":"hashtag","href":"/id-generation"},{"title":"Policy shrink","icon":"scissors","href":"/policy-shrink"},{"title":"Privilege analyzer","icon":"magnifying-glass","href":"/analyzer"},{"title":"Trust scoring","icon":"user-shield","href":"/trust"},{"title":"Anomaly detection","icon":"triangle-exclamation","href":"/anomaly"}]},{"group":"Controls","icon":"gauge","pages":[{"title":"Approval flows","icon":"user-check","href":"/approval"},{"title":"Step-up authentication","icon":"fingerprint","href":"/step-up-auth"},{"title":"Guard agent tools","icon":"shield-check","href":"/agent-tools"},{"title":"Taint-aware tool guard","icon":"droplet","href":"/taint-guard"},{"title":"Remote guards","icon":"shield-check","href":"/guards"},{"title":"Browser playground for taint guard and policy","icon":"flask-conical","href":"/playground"},{"title":"Vercel AI SDK","icon":"shield-check","href":"/vercel-ai-sdk"},{"title":"OpenAI Agents SDK","icon":"shield-check","href":"/openai-agents-sdk"},{"title":"Guard LangGraph and Mastra agent tools","icon":"plug","href":"/agent-frameworks"},{"title":"Vercel AI SDK helper","icon":"shield-check","href":"/integrations/vercel-ai-sdk"},{"title":"OpenAI Agents SDK helper","icon":"shield-check","href":"/integrations/openai-agents-sdk"},{"title":"LangGraph and CrewAI","icon":"plug","href":"/integrations/langgraph-crewai"},{"title":"Permission simulator","icon":"flask-conical","href":"/simulator"},{"title":"Explain a decision","icon":"search","href":"/explain"},{"title":"Rate limiting","icon":"shield-halved","href":"/rate-limiting"},{"title":"CLI login (device flow)","icon":"terminal","href":"/cli-auth"},{"title":"CLI tools","icon":"terminal","href":"/cli-tools"},{"title":"Agent registration tokens","icon":"ticket","href":"/agent-registration-tokens"},{"title":"Budget policies","icon":"dollar-sign","href":"/budget-policies"},{"title":"Cost attribution","icon":"chart-column","href":"/cost-attribution"}]},{"group":"Tutorials","icon":"graduation-cap","pages":[{"title":"Stop prompt injection from making an AI agent send email","icon":"droplet","href":"/tutorials/prompt-injection-tool-guard"},{"title":"Delegate a scoped token to an agent and revoke it","icon":"route","href":"/tutorials/agent-delegation-e2e"},{"title":"Find and remove unused permissions from an AI agent","icon":"scissors","href":"/tutorials/remove-unused-agent-permissions"},{"title":"Prove what your AI agent did without sharing your database","icon":"stamp","href":"/tutorials/verifiable-agent-receipts"},{"title":"Revoke an agent's MCP access and watch it fail on the next request","icon":"ban","href":"/tutorials/live-revocation"}]}]},{"tab":"Platform","icon":"layer-group","pages":[{"title":"Platform","href":"/mcp"}]},{"tab":"Advanced","icon":"sliders","pages":[{"title":"Advanced","href":"/compliance"}]},{"tab":"Migrate","icon":"arrow-right-arrow-left","pages":[{"title":"Migrate","href":"/migrate"}]},{"tab":"Reference","icon":"book","pages":[{"title":"Reference","href":"/api"}]},{"tab":"Compare","icon":"code-compare","pages":[{"title":"Compare","href":"/compare"}]},{"tab":"Go","icon":"golang","pages":[{"title":"Go","href":"/go"}]}]},"basePath":"","title":"Agent identity - theAuth","deploymentId":"dpl_vSEmv961Ncyvz1psVwgUnTXQMSYk","buildId":"dpl_vSEmv961Ncyvz1psVwgUnTXQMSYk","dynamics":["07c022d89b","a74be98ba7"],"chunks":["Frame-BRsfsIIG.js","DynamicMarkdown-NFqqduU7.js","zoom-image-lightbox-BguUeq2N.js","lightbox-handle-r17bVUz3.js"]}