What is an Agent Token in Clavex?

An Agent Token is an OAuth 2.0 Bearer access token issued to an AI agent (e.g. an MCP client) that delegates a bounded subset of a human user's permissions. It carries token_type=agent, agent_id, delegated_by, and scope claims, is signed with the same key as OIDC tokens, and can be revoked independently from the delegating user's browser session.

Who can issue an Agent Token?

Any org admin holding the 'users' resource permission — issuance is self-service per organisation, not a superadmin-only operation. Issue tokens from the Agent Tokens page in the admin console, or via POST /api/v1/organizations/{org}/agent-tokens.

What scopes does Clavex predefine for MCP?

mcp:read, mcp:write, mcp:tools:call, mcp:tools:list, mcp:resources:read, mcp:resources:write, mcp:prompts:read, and mcp:admin. Fetch the current list at GET /api/v1/organizations/{org}/agent-tokens/mcp-scopes (public, no auth required).

Can a user revoke an Agent Token issued on their behalf?

Yes. Any authenticated user can list and revoke the agent grants delegated by them via GET/DELETE /api/v1/me/agent-tokens, without needing admin permission — ownership is enforced from the JWT subject, never a request parameter.

Platform

Agent Tokens

Agent Tokens give every AI agent — an MCP client, a LangChain assistant, a custom copilot — its own bounded, auditable, revocable identity, instead of sharing a human's session or a long-lived static API key. Each token delegates a scoped subset of one user's permissions and can be revoked independently at any time.

How It Works

Org Admin ─────> Clavex Issue token — user + agent_id + scope + TTL

Clavex ─────> Org Admin signed JWT (shown once)

AI Agent ─────> MCP Server Authorization: Bearer <agent_token>

MCP Server ─────> Clavex JWKS verify signature + scope + expiry

Step 1 — Issue a Token (Self-Service, Org Admin)

Issuance requires the users resource permission — any org admin, not just a superadmin. In the admin console, open Agent Tokens and click Issue token: pick the delegating user, an agent_id (e.g. claude-mcp-v1), a scope, and a TTL. The signed token is shown once.

bash

$ curl -s -X POST https://id.clavex.eu/api/v1/organizations/$ORG_ID/agent-tokens \ -H "Authorization: Bearer $ORG_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "user_id": "01925f3a-...", "agent_id": "claude-mcp-v1", "agent_name": "Claude — Audit Copilot", "scope": "mcp:read mcp:tools:call", "ttl_seconds": 86400, "mcp_server_id": "clavex-mcp", "mcp_resource_url": "https://id.clavex.eu/api/v1/organizations/$ORG_ID/mcp" }' | jq '{token_id,expires_at}' { "token_id": "b3c1...", "expires_at": "2026-07-22T10:00:00Z" }

TTL: defaults to 24h, capped at 90 days (ttl_seconds max 7776000). Prefer short-lived tokens for interactive agent sessions.

Step 2 — Predefined MCP Scopes

Discover the current scope catalog (public endpoint, no auth):

bash

$ curl -s https://id.clavex.eu/api/v1/organizations/$ORG_ID/agent-tokens/mcp-scopes | jq .

Scope	Grants
mcp:read	Read access to MCP server resources (list tools, read outputs)
mcp:write	Write access to MCP server resources (invoke tools, store data)
mcp:tools:call	Permission to call any tool exposed by the MCP server
mcp:tools:list	Permission to list available tools without invoking them
mcp:resources:read	Read MCP resource URIs (files, databases, APIs)
mcp:resources:write	Write or update MCP resources
mcp:prompts:read	Read prompt templates from the MCP server
mcp:admin	Full administrative access to the MCP server (superscope)

Scope down to a single tool with a custom scope (e.g. mcp:tools:search) — the predefined list above is a reference, not an enforced enum. Combine with standard OIDC scopes (openid profile email) as needed.

Step 3 — Authenticate the Agent

The agent presents the token as a standard Bearer credential against Clavex's built-in MCP server (JSON-RPC 2.0 over HTTP) or any resource server that trusts Clavex's JWKS.

bash

$ curl -s -X POST https://id.clavex.eu/api/v1/organizations/$ORG_ID/mcp \ -H "Authorization: Bearer $AGENT_TOKEN" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Clavex's built-in MCP server exposes audit-copilot and identity-risk-advisor tools for natural-language compliance queries; see the standalone MCP server package (@clavex/mcp-server) for the npm-distributed client and full tool catalog rather than duplicating it here.

Cross-Cloud Audience (STS / Workload Identity Federation)

By default a token's aud claim is the Clavex issuer itself. Set audience to target an external OAuth2/OIDC-federation-aware resource server — e.g. AWS STS (sts.amazonaws.com), Azure AD (api://AzureADTokenExchange), or a GCP Workload Identity Federation pool provider. The requested audience must be present in the org's agent_token_allowed_audiences allowlist, otherwise the request is rejected with invalid_target — the same allowlist model used for RFC 8693 token-exchange audiences on OIDC clients.

Self-Service Revocation ("My Active Agents")

Any user — not just admins — can review and revoke the agents acting on their behalf:

bash

$ curl -s https://id.clavex.eu/api/v1/me/agent-tokens \ -H "Authorization: Bearer $USER_TOKEN" | jq .
$ curl -s -X DELETE https://id.clavex.eu/api/v1/me/agent-tokens/$TOKEN_ID \ -H "Authorization: Bearer $USER_TOKEN"

Every issuance and revocation is audited (agent.token.issued / agent.token.revoked) and fires a webhook, so security teams can track exactly which agents hold live grants and who created them.