Skip to main content
POST
Mint a capability token
The raw token is returned once, in this response. KnoxCall stores only a hash — no later call can retrieve it. Save it to your secrets manager immediately.
Tokens are kp_-prefixed since 2026-09-01 (kp_<env>_<kind>_…) — see the changelog; a token minted before that date no longer parses. Two behaviours worth knowing:
  • Omitting expires_in_seconds gives 30 days, not “never”. Any requested TTL is clamped to between 60 seconds and 90 days. Before 2026-08-30 an omitted expiry meant the token never expired.
  • The capability scope is empty, deliberately. This endpoint offers no parameter to set one, and an earlier revision guessed a provider restriction from the model name — which mislabelled every Gemini, Mistral and Cohere agent and would have refused the token’s own traffic. An empty scope means “no token-level restriction”, which is the truth. See Scoping for what a scope enforces when one is present, and how to get one today.
dpop_required: true requires dpop_jkt in the same request — a DPoP-bound token with no key thumbprint is unusable, so it is refused with 400 validation rather than minted.
The dashboard twin. The same operation exists on the admin host as POST /admin/ai-gateway/{gatewayId}/agents/{agentId}/keys, session-authenticated with an X-Tenant-ID header and an owner/admin role. That is what the dashboard itself calls. Prefer the /v1 operation above for anything you write: it is the surface the five SDKs, the Postman collection and this spec cover.

Authorizations

Authorization
string
header
required

OAuth 2.1 authentication — recommended for new integrations. Access tokens (kc_ prefix) are minted at the root-host token endpoint https://api.knoxcall.com/oauth/token and passed as Authorization: Bearer <access_token>. Public clients must use PKCE with the authorization_code grant; confidential clients may use client_credentials. The first-party SDKs and the knoxcall login CLI handle token minting, caching, refresh, and DPoP for you.

Path Parameters

agentId
string<uuid>
required

The AI agent UUID.

Body

application/json
name
string

A human-readable label for the token.

kind
enum<string>
default:agent
Available options:
agent,
read,
tool,
oneshot
dpop_required
boolean
default:false

Bind the token to a DPoP key. Requires dpop_jkt.

dpop_jkt
string

base64url SHA-256 thumbprint of your DPoP public key. Required when dpop_required is true.

expires_in_seconds
integer

Token lifetime, clamped to [60s, 90d]. Omit for the 30 days default; a non-expiring token cannot be minted.

Required range: 60 <= x <= 7776000

Response

The minted token. data.token is the plaintext, shown once; meta.note restates the warning.

data
object

The mint result. token is the plaintext capability token and is shown exactly once.

meta
object