REST API reference

Principal endpoints (grants, approvals, audit, revoking by id) require the admin token as Authorization: Bearer <admin token>. Agent endpoints take the agent token in the request body, so a tool server can forward it without extra headers.

The full OpenAPI 3.1 description is openapi.yaml. A test keeps it in sync with the routes the server exposes.

Method and path	Auth	Purpose
GET /healthz	none	Liveness check
GET /.well-known/jwks.json	none	Public signing keys
POST /v1/grants	admin	Create a grant
GET /v1/grants	admin	List grants
GET /v1/grants/{id}	admin	Get a grant and its tokens
POST /v1/grants/{id}/revoke	admin	Revoke a grant
POST /v1/tokens/attenuate	token	Derive a narrower token
POST /v1/tokens/introspect	token	Report whether a token is active
POST /v1/tokens/revoke	token or admin	Revoke a token and its descendants
POST /v1/check	token	Decide whether a token permits a request
GET /v1/approvals	admin	List approval requests
POST /v1/approvals/{id}/approve	admin	Approve a pending request
POST /v1/approvals/{id}/deny	admin	Deny a pending request
GET /v1/audit	admin	Read audit entries
GET /v1/audit/verify	admin	Verify the audit hash chain on the server

Operations

Liveness check

GET /healthz (operation health)

Responses:

• 200: The server is up.

Public signing keys

GET /.well-known/jwks.json (operation jwks)

Use these keys to verify agent tokens offline.

Responses:

• 200: A JSON Web Key Set with one Ed25519 key.

Create a grant

POST /v1/grants (operation createGrant)

Delegates scopes to an agent and returns the grant with its root token.

Responses:

• 201: Grant created.
• 400: Invalid input (bad_request or invalid_scope).
• 401: Missing admin token, or an invalid, expired or revoked agent token.

List grants

GET /v1/grants (operation listGrants)

Responses:

• 200: Grants, newest first.
• 401: Missing admin token, or an invalid, expired or revoked agent token.

Get a grant and its tokens

GET /v1/grants/{id} (operation getGrant)

Responses:

• 200: The grant and every token issued under it.
• 401: Missing admin token, or an invalid, expired or revoked agent token.
• 404: No such resource.

Revoke a grant

POST /v1/grants/{id}/revoke (operation revokeGrant)

Revokes the grant and every token issued under it.

Responses:

• 200: Ids of the tokens that this call revoked.
• 401: Missing admin token, or an invalid, expired or revoked agent token.
• 404: No such resource.

Derive a narrower token

POST /v1/tokens/attenuate (operation attenuate)

Every requested scope must be covered by a single scope of the parent token. The child expires no later than the parent, and its use limit is no higher than the parent's.

Responses:

• 201: Child token issued.
• 400: Invalid input (bad_request or invalid_scope).
• 401: Missing admin token, or an invalid, expired or revoked agent token.
• 403: scope_escalation or depth_exceeded.

Report whether a token is active

POST /v1/tokens/introspect (operation introspect)

Responses:

• 200: Token status. Never consumes a use.

Revoke a token and its descendants

POST /v1/tokens/revoke (operation revokeToken)

Pass token to revoke the presented token. Pass jti with the admin token to revoke any token by id.

Responses:

• 200: Ids of the tokens that this call revoked.
• 400: Invalid input (bad_request or invalid_scope).
• 401: Missing admin token, or an invalid, expired or revoked agent token.
• 404: No such resource.

Decide whether a token permits a request

POST /v1/check (operation check)

Returns allow, deny or approval_required. An allow consumes one use on every token in the chain unless dryRun is true. Every call is written to the audit log. An invalid, expired or revoked token yields deny with HTTP 200, so tool servers handle one response shape.

Responses:

• 200: The decision.
• 400: Invalid input (bad_request or invalid_scope).

List approval requests

GET /v1/approvals (operation listApprovals)

Responses:

• 200: Approvals, oldest first.
• 400: Invalid input (bad_request or invalid_scope).
• 401: Missing admin token, or an invalid, expired or revoked agent token.

Approve a pending request

POST /v1/approvals/{id}/approve (operation approve)

Responses:

• 200: Updated approval.
• 404: No such resource.
• 409: The approval has already been decided.

Deny a pending request

POST /v1/approvals/{id}/deny (operation deny)

Responses:

• 200: Updated approval.
• 404: No such resource.
• 409: The approval has already been decided.

Read audit entries

GET /v1/audit (operation listAudit)

Responses:

• 200: Entries in sequence order.
• 400: Invalid input (bad_request or invalid_scope).
• 401: Missing admin token, or an invalid, expired or revoked agent token.

Verify the audit hash chain on the server

GET /v1/audit/verify (operation verifyAudit)

For an independent check, download the entries with /v1/audit and verify them yourself, for example with agent-auth audit verify.

Responses:

• 200: Verification result.
• 401: Missing admin token, or an invalid, expired or revoked agent token.