REST API - theAuth

All REST endpoints are mounted by the framework adapter (Hono, Express, Next.js, etc.). Paths below are relative to the mount path. The Next.js, Astro, Fastify, and NestJS adapters default to /api/theauth (set with their basePath or prefix option); with Hono and Express you pick the mount path yourself, for example app.route('/api/theauth', theAuthHono(theauth, { authenticate })).

The agent, delegation, audit and dashboard routes (/agents, /delegations, /audit, /dashboard) and POST /authorize require an authenticated caller. Pass authenticate to the adapter, or configure auth.session so the adapter accepts any signed-in user. With neither, the adapter throws when you create it, unless you set allowUnauthenticated: true (local development only). Unauthenticated requests get 401 UNAUTHORIZED. See Framework adapters. POST /authorize/token is checked by the agent’s own kv_ bearer token, and the MCP, password reset and email verification routes carry their own checks.

Successful responses wrap the payload as { "data": ... }. Errors use { "error": { "code": "...", "message": "..." } } with codes such as BAD_REQUEST (400), UNAUTHORIZED (401), NOT_FOUND (404), and INTERNAL_ERROR (500). Examples below show the payload inside data. Dates are ISO 8601 strings and IDs are UUIDs (the agt_... IDs in the examples are illustrative). The MCP OAuth endpoints are the exception: they return bare OAuth JSON.

Agent endpoints

Create agent

POST /agents

Creates a new agent identity. Request body

{
  "ownerId": "user_01abc",
  "name": "GitHub Automation",
  "type": "autonomous",
  "permissions": [
    {
      "resource": "mcp:github:*",
      "actions": ["read", "write"],
      "constraints": {
        "maxCallsPerHour": 100
      }
    }
  ],
  "expiresAt": "2026-12-31T23:59:59Z",
  "metadata": {}
}

ownerId, name, type, and at least one permission are required. expiresAt is optional: when omitted, the agent expires after agents.tokenExpiry (default 24h). The owner must already exist as a row in theauth_users. Fields not listed here, such as tenantId, are ignored by the REST endpoint. Response 201 Created

{
  "id": "agt_01abc",
  "ownerId": "user_01abc",
  "name": "GitHub Automation",
  "type": "autonomous",
  "token": "kv_...",
  "status": "active",
  "permissions": [...],
  "expiresAt": "2026-12-31T23:59:59.000Z",
  "createdAt": "2026-03-21T10:00:00.000Z",
  "updatedAt": "2026-03-21T10:00:00.000Z"
}

The token (kv_ followed by 43 base64url characters) is returned only here and from the rotate endpoint. Every other endpoint returns "token": "". Validation failures return 400.

List agents

GET /agents

Returns agents, optionally filtered. With no filters it returns every agent. Query parameters

Parameter	Type	Description
`userId`	`string`	Filter by owner
`status`	`active \| revoked \| expired`	Filter by status
`type`	`autonomous \| delegated \| service`	Filter by agent type

Unrecognized status or type values are ignored rather than rejected. Response 200 OK - Array of agent objects.

Get agent

GET /agents/:id

Returns a single agent by ID. Response 200 OK - Agent object. 404 when not found.

Update agent

PATCH /agents/:id

Updates name, permissions, expiry, or metadata. Request body

{
  "name": "Updated Name",
  "permissions": [...],
  "expiresAt": "2027-01-01T00:00:00Z",
  "metadata": { "env": "production" }
}

All fields are optional. Passing permissions replaces the full permission list. Response 200 OK - Updated agent object, or 404 when not found.

Revoke agent

DELETE /agents/:id

Permanently revokes an agent. Revoked agents cannot be reactivated. Response 204 No Content, or 404 when not found.

Rotate agent token

POST /agents/:id/rotate

Issues a new token and invalidates the previous one. Use this for credential rotation. Only active agents can be rotated. Response 200 OK - Agent object with a new token value. 404 when not found; 500 with the message Cannot rotate token for <status> agent. when the agent is revoked or expired.

Authorization endpoints

Authorize a request

POST /authorize

Checks whether an agent has permission to perform an action on a resource. The agent’s own permissions are checked first, then permissions it holds through delegation. Budget policies are not checked here. Request body

{
  "agentId": "agt_01abc",
  "action": "write",
  "resource": "mcp:github:create_issue",
  "arguments": {
    "repo": "org/repo",
    "title": "Bug fix"
  }
}

agentId, action, and resource are required. The client IP and User-Agent are stored on the audit entry. The IP comes from the adapter’s trustedProxy setting (trustedProxyCount or trustedHeader). With neither set, forwarded headers are ignored and the IP is unknown, so an ipAllowlist constraint denies. Express, Fastify and NestJS fall back to the socket address. A context object in the body is ignored. Response 200 OK when allowed

{
  "allowed": true,
  "auditId": "7b0c1d52-..."
}

Response 403 Forbidden when denied. The body is still wrapped in data, and reason is free text, not a code:

{
  "allowed": false,
  "reason": "Rate limit exceeded: 100/100 calls per hour for resource \"mcp:github:create_issue\"",
  "auditId": "7b0c1d52-..."
}

For an unknown or inactive agent the response is also 403, with an empty auditId because no audit entry is written.

Authorize by agent token

POST /authorize/token
Authorization: Bearer kv_...

Same check, but the agent is identified by its bearer token instead of agentId. The body takes action, resource, and optional arguments. A missing or malformed Authorization header returns 401 UNAUTHORIZED. An invalid, revoked, or expired token returns 403 with reason: "Invalid or expired agent token". This path checks only the agent’s own permissions, not delegated ones.

Delegation endpoints

Create delegation

POST /delegations

Delegates a subset of permissions from one agent to another. The permissions must be a subset of what fromAgent holds itself. Request body

{
  "fromAgent": "agt_01abc",
  "toAgent": "agt_02def",
  "permissions": [
    { "resource": "mcp:github:*", "actions": ["read"] }
  ],
  "expiresAt": "2026-06-01T00:00:00Z",
  "maxDepth": 2
}

fromAgent, toAgent, at least one permission, and expiresAt are required. maxDepth defaults to 3; the new link’s depth must be less than or equal to it, otherwise the call fails with 400. An unknown parent agent returns 404. A permission set that is not a subset of the parent’s currently surfaces as 500 INTERNAL_ERROR with the explanatory message. Response 201 Created

{
  "id": "del_01abc",
  "fromAgent": "agt_01abc",
  "toAgent": "agt_02def",
  "permissions": [...],
  "depth": 1,
  "expiresAt": "2026-06-01T00:00:00.000Z",
  "createdAt": "2026-03-21T10:00:00.000Z"
}

List delegations

GET /delegations/:agentId

Returns the delegation chains where :agentId is the source agent (fromAgent). There are no query parameters, and there is no endpoint that lists every delegation. Response 200 OK - Array of delegation objects.

Revoke delegation

DELETE /delegations/:id

Revokes a delegation chain immediately, and cascades to chains the target agent has delegated onward. Response 204 No Content, or 404 when not found.

Audit endpoints

Query audit log

GET /audit

Returns audit log entries matching the specified filters. Query parameters

Parameter	Type	Description
`agentId`	`string`	Filter by agent
`userId`	`string`	Filter by user
`since`	`ISO 8601`	Start of time range
`until`	`ISO 8601`	End of time range
`actions`	`string` (comma-separated)	Filter by action names
`result`	`allowed \| denied \| rate_limited`	Filter by outcome
`limit`	`number`	Max results (no default; all matches when omitted)
`offset`	`number`	Pagination offset

Entries are returned newest first. Invalid dates, non-positive limit, and negative offset values are ignored. The actions filter is applied after limit and offset, so a page can come back shorter than limit. Authorization decisions are recorded only as allowed or denied, so result=rate_limited currently matches nothing. Response 200 OK

[
  {
    "id": "aud_01xyz",
    "agentId": "agt_01abc",
    "userId": "user_01abc",
    "action": "write",
    "resource": "mcp:github:create_issue",
    "parameters": { "repo": "org/repo" },
    "result": "allowed",
    "durationMs": 3,
    "timestamp": "2026-03-21T10:00:00.000Z"
  }
]

Denied entries also carry a free-text reason. tokensCost appears only on entries that recorded one. The IP address and user agent are stored but not returned.

Export audit log

GET /audit/export?format=json&since=2026-01-01

Exports the audit log as JSON or CSV, as evidence for compliance work. The export contains at most the 10,000 most recent matching entries. Query parameters

Parameter	Type	Description
`format`	`json \| csv`	Output format. Defaults to `json`; any other value returns `400`.
`since`	`ISO 8601`	Start of time range
`until`	`ISO 8601`	End of time range

Response 200 OK - File download (audit-export.json or audit-export.csv) with Content-Disposition: attachment. The body is not wrapped in data. CSV columns are id, agentId, userId, action, resource, result, reason, durationMs, tokensCost, timestamp; request parameters appear only in the JSON export.

MCP endpoints

These endpoints implement the MCP OAuth 2.1 specification. They are served only when you pass an MCP module to the adapter (theAuthHono(theauth, { mcp, authenticate }), built with createMcpModule from @glinr/theauth/mcp); otherwise they return 404 with MCP module not configured. Responses are bare OAuth JSON (no data wrapper), errors look like { "error": "invalid_request", "error_description": "..." }, and CORS is open (Access-Control-Allow-Origin: *).

Authorization Server Metadata

GET /.well-known/oauth-authorization-server

Returns OAuth 2.0 Authorization Server Metadata (RFC 8414). Public endpoint, no auth required.

Protected Resource Metadata

GET /.well-known/oauth-protected-resource

Returns Protected Resource Metadata (RFC 9728). Public endpoint, no auth required.

Dynamic Client Registration

POST /mcp/register

Registers a new OAuth client (RFC 7591). Registration is open: the endpoint itself does not authenticate callers. Request body - See RFC 7591 for the full schema. Minimum:

{
  "redirect_uris": ["https://my-mcp-client.example.com/callback"],
  "client_name": "My MCP Client"
}

Response 201 Created (with Cache-Control: no-store) - Client metadata including client_id. A client_secret is included for confidential clients, which is the default (token_endpoint_auth_method of client_secret_basic); clients that register with none get no secret. Invalid metadata returns 400 with invalid_client_metadata.

Authorization request

GET /mcp/authorize?response_type=code&client_id=...&redirect_uri=...&code_challenge=...&code_challenge_method=S256

Starts the OAuth authorization code flow. Requires PKCE (code_challenge + code_challenge_method=S256). Responds with a 302 redirect: to the module’s loginPage (with a returnTo parameter) if resolveUserId finds no signed-in user, to consentPage when one is configured, and otherwise to your redirect_uri with the authorization code. Request errors return 400 with an OAuth error code.

Token exchange

POST /mcp/token

Exchanges an authorization code or refresh token for an access token. Confidential clients authenticate with client_secret_basic or client_secret_post. Request body (application/x-www-form-urlencoded) For authorization_code grant:

grant_type=authorization_code
&code=<code>
&redirect_uri=<redirect_uri>
&client_id=<client_id>
&code_verifier=<pkce_verifier>

For refresh_token grant:

grant_type=refresh_token
&refresh_token=<token>
&client_id=<client_id>

Response 200 OK (with Cache-Control: no-store)

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "...",
  "scope": "mcp:read mcp:execute"
}

refresh_token is present only when the granted scope includes offline_access. expires_in is the module’s accessTokenTtl. Failures return 401 for invalid_client and 400 for everything else.

Dashboard endpoints

Stats overview

GET /dashboard/stats

Returns aggregate statistics for the admin dashboard. The audit counts cover the last 24 hours and are computed from at most the 1,000 most recent entries. Response 200 OK

{
  "agents": { "total": 42, "active": 38, "revoked": 3, "expired": 1 },
  "users": { "total": 12 },
  "audit": { "last24h": 480, "allowed": 470, "denied": 10, "rateLimited": 0 }
}

Dashboard agents and audit

GET /dashboard/agents
GET /dashboard/audit

Aliases for GET /agents and GET /audit, with the same query parameters and responses.

Password reset and email verification

POST /auth/forgot-password
POST /auth/reset-password
POST /auth/verify-email/send
POST /auth/verify-email/confirm

These forward the request to theauth.passwordReset and theauth.emailVerification, which exist only when you pass passwordReset or emailVerification to createTheAuth (and, for password reset, username and auth.session). When the module is not configured the route returns 404. Request and response bodies are defined by those modules, not by the agent endpoints above.

Adapters overview

Framework adapters that mount these endpoints on your server.

Agent identity

Core concepts behind the agent endpoints and token lifecycle.

Audit

Querying and exporting audit logs via the REST API.

Errors

Error codes and HTTP status reference for all endpoints.

​Agent endpoints

​Create agent

​List agents

​Get agent

​Update agent

​Revoke agent

​Rotate agent token

​Authorization endpoints

​Authorize a request

​Authorize by agent token

​Delegation endpoints

​Create delegation

​List delegations

​Revoke delegation

​Audit endpoints

​Query audit log

​Export audit log

​MCP endpoints

​Authorization Server Metadata

​Protected Resource Metadata

​Dynamic Client Registration

​Authorization request

​Token exchange

​Dashboard endpoints

​Stats overview

​Dashboard agents and audit

​Password reset and email verification

​Related