API reference

Two surfaces: the OAuth endpoints under /t/:slug (for services and resource servers) and the management API under /api (for the admin UI and automation). <issuer> below is <PUBLIC_URL>/t/<slug>.

OAuth endpoints

All bodies are application/x-www-form-urlencoded (anything else is 400 invalid_request) and at most 16 KiB (413 invalid_request). Responses carry Cache-Control: no-store. Errors are {"error": "<code>", "error_description": "<text>"}.

Client authentication (token, introspect, revoke): Authorization: Basic base64(urlencode(client_id):urlencode(client_secret)) for applications registered as client_secret_basic, or client_id + client_secret in the body for client_secret_post. For private_key_jwt applications send client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer and client_assertion=<ES256 JWT> in the body (both together; an optional client_id must equal the assertion’s iss). The registered method is enforced; sending two methods, or only one of the two assertion parameters, is 400 invalid_request. Assertion rules (RFC 7523): header alg=ES256 and the kid of a registered active key (or of a retiring key before its retiresAt); iss = sub = client_id; aud = <issuer>/oauth/token exactly, also on introspect and revoke; exp required and at most 300 s ahead; iat at most 60 s ahead; a unique jti (the replay cache is per process, see deployment); 60 s clock tolerance. Every failure is the same 401 invalid_client. client_id has the form app_ plus 20 characters, the secret hs_ plus 48.

Token endpoint errors (HTTP status, error, cause):

Rate limits (per minute, per IP and per client_id): token 600 / 600, introspect 1200 / 600, revoke 200 / 100; configurable (see README).

Human approval grant

An agent application that asks (explicitly, or by omitting scope) for a scope with agent_policy=approval gets no token. Handsal opens an approval request and answers:

400 {"error":"authorization_pending","error_description":"Waiting for human approval of one or more requested scopes","approval_id":"<uuid>","interval":5}

interval is the minimum number of seconds between polls. A request that mixes auto and approval scopes goes pending as a whole. Guardrails (CIDR, scope ceiling, budget) and agent_policy=never are checked first, so a request that would fail anyway never reaches the queue. Sending the same request again returns the same approval_id while a live row has the same scopes, task_id, actor_hint and justification; an approved row not yet redeemed is reused too. At most 20 live pending requests exist per application: the 21st is 400 access_denied (reason approval_queue_full). If a tenant auto-approve rule covers every approval scope of the request, the row is created already approved and the response carries interval: 0: poll at once. The first request accepts two more optional form parameters, actor_hint (up to 255 characters, who the agent works for, shown to the approver) and justification (up to 2000 characters). A pending request expires after 30 minutes. The first request records a pending token event; polls that stay pending record none.

Poll with grant_type=urn:handsal:params:grant-type:approval and approval_id=<uuid>, authenticating the same way as the first request. The poll takes no resource, scope or task_id: sending any of them is 400 invalid_request. When the request was approved the response is the usual 200 {access_token, token_type, expires_in, scope} with the approved audience, scopes and task_id; the TTL is 300 s regardless of the application or resource TTL. Each approval yields exactly one token; the issued event has reason approval. Redemption checks again that the grant and resource still exist, and re-runs the agent guardrails (CIDR, scope ceiling, budget) and the agent_policy check. CIDR and budget run before the claim, so a refused poll (unauthorized_client with reason cidr_denied, 429 too_many_requests with reason budget_exhausted) does not consume the approval. A scope demoted to never or deleted meanwhile is invalid_grant with reason policy_changed. Denied and expired poll events carry the row’s audience and scopes. Resolved rows are deleted 30 days after their expiry time (expires_at, never earlier than the decision) by the hourly approval-retention job (1000 per run); the approval-expiry job also works in batches of 1000.

Token exchange grant

RFC 8693 delegation: an agent application trades a subject token for an access token whose sub is the subject and whose act names the agent. The application needs a non-empty mayActFor (Applications). Form parameters:

actor_token and actor_token_type are not supported (400 invalid_request, checked before resource). The response is 200 {access_token, issued_token_type:"urn:ietf:params:oauth:token-type:access_token", token_type:"Bearer", expires_in, scope}; the TTL follows the normal chain (application, resource, tenant default). The subject is verified first as a token of this tenant (valid signature, not expired or revoked, aud equal to resource), then against the tenant’s externalIdp (signature via its jwksUri with RS256, PS256, ES256, ES384 or EdDSA, iss, aud, exp required, 5 s tolerance; a sub is required).

The access token has sub = the subject’s sub, client_id = the agent’s client ID, sub_kind (user for an external IdP subject, service for a service token, agent for an agent token; an exchanged subject keeps its sub_kind across hops). mayActFor is checked against the class derived from it: user needs users, service needs services or tenant, agent needs tenant, and act: {"sub":"<agent client_id>"}. If a Handsal subject token carried an act, it is nested inside: {"sub":"<agent>","act":{...previous}}, most recent actor outermost, at most 3 levels; an external IdP’s act is ignored. Scopes: with delegationScopeMode=intersection (default) the candidate scopes are the agent’s grants on the resource that also appear, by name, in the subject’s scope (string or array) or scp array claim, and a subject without scopes shares none; with agent_only they are the agent’s grants. A requested scope must be inside the candidates. The guardrails of the agent (CIDR, scope ceiling, hourly budget) apply, and so does agent_policy: a never scope is invalid_scope, an approval scope is invalid_scope with scope requires human approval; request it with the approval grant (an exchange is never queued).

Token log reasons for exchange denials: exchange_not_allowed, invalid_subject_token, act_chain_too_deep, may_act_for_denied, approval_required, plus the usual invalid_target, invalid_scope, scope_ceiling, cidr_denied, budget_exhausted. An issued event records the subject in actorSub.

Access token: JWT, header {alg:"ES256", kid, typ:"at+jwt"}, claims iss (<issuer>), sub and client_id (the application’s client ID), aud (the resource), scope, tenant (slug), client_kind (service or agent), jti (UUID), iat, exp, and task_id when one was passed, and act + sub_kind on exchanged tokens (there sub is the delegating subject and client_id the agent). TTL is application.tokenTtlSeconds ?? resource.tokenTtlSeconds ?? tenant.defaultTokenTtlSeconds (default 3600; 60 to 86400 everywhere).

Instance endpoints

Management API (/api)

Available unless ENABLE_ADMIN_PANEL=false (then 404 {"error":"not_found"}). JSON in and out; bodies up to 512 KiB (413 payload_too_large). Timestamps are ISO 8601 strings, IDs are UUIDs. Errors: {"error": "<code>", "error_description": "<text>", "details"?: ...}.

Authentication

• Session: POST /api/auth/login with {email, password} sets the handsal_session cookie (HttpOnly, SameSite=Strict, Secure in production, 12 h) and returns {user:{id,email,name,isSuperAdmin}, csrfToken}. Send that cookie and the token as X-CSRF-Token on every POST, PUT, PATCH and DELETE; without the token the call fails with 403 csrf_required. Scripts use the same login. A bearer token is not accepted.
• Roles per tenant: auditor (read), admin (everything except members, pause/resume, revoke-all-tenant, delete tenant), owner (everything). A super-admin counts as owner everywhere. A tenant that does not exist or that you are not a member of is 404 tenant_not_found; a role that is too low is 403 forbidden.

Common errors on every route: 401 unauthenticated, 403 csrf_required, 400 validation_error (details holds the flattened Zod errors), 404 tenant_not_found, 403 forbidden.

Tenants

Tenant: {id, name, slug, status:"active"|"paused", defaultTokenTtlSeconds, introspectionEnabled, keyRotationDays, externalIdp, approvalWebhookUrl, approvalWebhookSecretSet, tokensNotBefore, issuer, createdAt, updatedAt}.

• externalIdp: {issuer, jwksUri, audience} or null. A trusted identity provider whose JWTs may be the subject_token of a token exchange; jwksUri must be https in production; one IdP per tenant. JWKS fetches do not follow redirects, and at most 100 JWKS caches are held per process.
• approvalWebhookUrl: where Handsal POSTs new pending approvals (see the integration guide), or null. Must be https in production.
• approvalWebhookUrl and externalIdp.jwksUri pass an outbound URL guard (400 validation_error): https is required in production (http is also allowed elsewhere). In production, literal loopback, link-local, RFC 1918, CGNAT (100.64/10), 0/8 and unique-local addresses, and the names localhost, *.localhost, *.internal and *.local, are rejected. A hostname is resolved and refused when any answer is internal; a name that cannot be resolved is 400 (“could not be resolved”). The fetch then connects only to the address resolved before the request, and redirects are not followed. Outside production those addresses are allowed and names are not resolved.
• approvalWebhookSecret is write-only (16-255 characters, stored encrypted); reads return approvalWebhookSecretSet: true|false. Send null to remove it.

Applications

Application: {id, name, description, kind:"service"|"agent", clientId, tokenEndpointAuthMethod ("client_secret_basic"|"client_secret_post"|"private_key_jwt"), tokenTtlSeconds, status:"active"|"disabled", secretRotatedAt, previousSecretExpiresAt, tokensNotBefore, lastTokenAt, createdAt, updatedAt, agentRuntime, operatorEmail, allowedCidrs, maxScopesPerToken, tokenBudgetPerHour, mayActFor, delegationScopeMode}. agentRuntime to tokenBudgetPerHour are agent fields: null ([] for allowedCidrs) on services and when unset. mayActFor (array of users, tenant, services; default []) and delegationScopeMode (intersection default, or agent_only) configure token exchange and are accepted for agent applications only (400 agent_fields_on_service otherwise); an empty mayActFor disables exchange. Reset them with [] / "intersection", not null. Unknown body keys are rejected on create.

Agent fields (agentRuntime up to 64 chars, operatorEmail, allowedCidrs up to 20 entries such as 10.0.0.0/8 or 2001:db8::/32, maxScopesPerToken 1-50, tokenBudgetPerHour 1-100000) are rejected on service applications with 400 agent_fields_on_service; an unparsable CIDR is 400 invalid_cidr. Enforcement is described in the integration guide.

... is /api/tenants/:tenantId. “Revoke all” invalidates tokens issued before the call (visible in introspection); it does not change the client secret.

Application keys (private_key_jwt)

Public keys of an application, used to verify its client assertions. Key: {id, applicationId, kid, algorithm:"ES256", fingerprintSha256, status:"active"|"retiring", retiresAt, createdAt, updatedAt}; the public key itself is not returned.

A non-UUID :keyId is also 404 application_key_not_found. Switching an application to private_key_jwt needs at least one active key (409 no_application_key); retiring or deleting the last one afterwards is allowed and locks the client out.

Approvals

Requests of agent applications for approval scopes (see Human approval). Approval: {id, applicationId, applicationName, clientId, audience, scopes, actorHint, taskId, justification, status:"pending"|"approved"|"denied"|"expired", expiresAt, createdAt, decidedAt, decidedBy}; decidedBy is {kind:"user"|"rule"|"api-key", label} or null while pending; the label is snapshotted when the decision is made, so deleting the user or rule later keeps the name. api-key appears only on decisions stored before that credential was removed.

counts: {pending, oldestPendingAt, approvedToday, deniedToday, medianWaitSeconds, rules}; “today” is the trailing 24 h, medianWaitSeconds is null without decisions, rules is the number of auto-approve rules. Approving does not issue a token: the agent’s next poll does.

Approval rules

Auto-approve rules: when every approval scope of a request has at least one matching rule, the request is approved without a human (decidedBy.kind is rule). A rule on one scope never approves another scope. Rule: {id, scopeId, scopeName, resourceName, condition, action:"auto_approve", createdBy, createdAt}. condition keys are ANDed and all optional: application_ids (up to 50 UUIDs), task_id_prefix (1-128 chars; the request needs a task_id starting with it), max_scopes (1-50; at most this many scopes in the request); {} matches every request for the scope. Unknown keys are 400 validation_error. task_id is asserted by the agent and is not an authorization boundary, so a condition with only task_id_prefix is 400 invalid_rule_condition; combine it with application_ids. A rule can only be created on a scope with agent_policy=approval. There is no PATCH: delete and recreate. Rules are managed through the API only.

Resources and scopes

Resource: {id, name, kind:"api"|"mcp", audience, tokenTtlSeconds, status, createdAt, updatedAt}. The audience is a URL or a URN and is the exact string clients pass as resource. Scope: {id, resourceId, name, description, agentPolicy, createdAt, updatedAt}; the name matches ^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,127}$. agentPolicy (auto, approval, never): never keeps the scope out of tokens of agent applications (invalid_scope); approval makes an agent’s request wait for a human (Human approval); auto issues directly. Services are not affected.

Signing keys

Members

Member: {adminUserId, email, name, role, isActive, lastLoginAt, createdAt}.

Token log

Event: {id, applicationId, applicationClientId, resourceId, audience, outcome, reason, scopes, jti, expiresAt, sourceIp, createdAt, taskId, actorSub}; outcome is issued, denied, revoked or pending (approvals); taskId is set on tokens issued with a task_id; actorSub is the delegating subject of an exchanged token (null otherwise); a pending event is written when an approval request is opened. reason on denied events is the OAuth error code or one of unknown_client, auth_method_mismatch, bad_secret, client_disabled, tenant_paused, and, for private_key_jwt and agents: bad_assertion (wrong alg, signature, claims or lifetime), unknown_assertion_key (no active or unexpired retiring key with that kid), assertion_expired (exp or nbf failed), assertion_replayed (jti seen before), cidr_denied (source IP outside allowedCidrs), cidr_invalid (a stored CIDR could not be parsed), scope_ceiling (over maxScopesPerToken), budget_exhausted (hourly budget); approvals: approval_denied, approval_expired, invalid_grant; exchange: see Token exchange. Denials for agent_policy=never scopes are logged as invalid_scope. Events are purged after TOKEN_EVENTS_RETENTION_DAYS.