> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Tokens (v1)
> List, mint, and revoke an agent's phantom tokens over the public /v1 Management API. Plaintext is returned exactly once, at mint time.
# Phantom tokens
A **phantom token** is the short-lived capability token your application presents on the [data plane](/api-reference/ai-gateway/execute) to call an agent — your app never holds a raw provider API key. These endpoints manage the tokens for one agent over the `/v1` control plane. See the [control-plane overview](/api-reference/ai-gateway/control-plane-overview) for authentication and the response envelope.
The raw token value is returned **exactly once**, in the mint response. KnoxCall stores only a hash — list responses never contain plaintext. Save the minted token to your secrets manager immediately.
## Token format and environment
Tokens are formatted `kc____`, e.g. `kc_live_a_1a2b3c…`. The `prefix` field is the first 12 characters (`kc_live_a_` plus two characters), safe to display and store for identification.
The environment segment is derived from the key you mint with — a test key mints a `kc_test_…` token, a live key mints a `kc_live_…` token. There is no environment parameter on the request.
| `kind` | Prefix letter | Use |
| --------- | ------------- | --------------------------------------- |
| `agent` | `a` | Full-scope agent invocations (default). |
| `read` | `r` | Read-only invocations. |
| `tool` | `t` | Tool-bound. |
| `oneshot` | `o` | One-shot ephemeral. |
## List tokens
```http theme={"dark"}
GET /v1/ai-gateway/agents/{agentId}/tokens
```
Returns the agent's tokens, paginated (`page`, `per_page`), newest first. Requires the `read` capability. **Never returns plaintext.** Returns `404 not_found` if the agent does not belong to your tenant or is a system agent.
```bash theme={"dark"}
curl "https://api.knoxcall.com/v1/ai-gateway/agents/7c4d2e9f-1a3b-4c6d-8e0f-2a4b6c8d0e1f/tokens" \
-H "Authorization: Bearer tk_live_abc123..."
```
**Response**
```json theme={"dark"}
{
"data": [
{
"id": "b1a2c3d4-e5f6-4789-abcd-1234567890ef",
"name": "CI pipeline token",
"kind": "agent",
"prefix": "kc_live_a_a4",
"dpop_required": false,
"scope_jsonb": { "providers": ["anthropic"], "models": ["claude-sonnet-4-6"] },
"expires_at": "2026-08-05T12:00:00.000Z",
"revoked_at": null,
"last_used_at": "2026-07-06T09:15:00.000Z",
"created_at": "2026-07-06T12:00:00.000Z"
}
],
"meta": {
"total": 1,
"page": 1,
"per_page": 20,
"total_pages": 1,
"request_id": "0d5b2a9e-1f3c-4a7d-8e2b-6c9a1f4d7e35"
}
}
```
## Mint a token
```http theme={"dark"}
POST /v1/ai-gateway/agents/{agentId}/tokens
```
Mints a new phantom token for the agent and returns the plaintext once. Requires the `mint` capability on `ai_gateway`.
**Request body** — all fields optional.
| Field | Type | Description |
| -------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `name` | string | Label for the token. Defaults to `key-`. |
| `kind` | `agent` \| `read` \| `tool` \| `oneshot` | Token kind. Defaults to `agent`; an unrecognized value falls back to `agent`. |
| `dpop_required` | boolean | Bind the token to a DPoP key. Defaults to `false`. |
| `dpop_jkt` | string | Base64url SHA-256 JWK thumbprint of your DPoP public key. **Required when `dpop_required` is `true`.** |
| `expires_in_seconds` | number | TTL in seconds, clamped to `[60, 7776000]` (1 minute to 90 days). Omit for a non-expiring token. |
The token's capability scope (providers and models) is derived automatically from the agent's `default_model`. It is not accepted from the request body.
```bash cURL theme={"dark"}
curl -X POST https://api.knoxcall.com/v1/ai-gateway/agents/7c4d2e9f-1a3b-4c6d-8e0f-2a4b6c8d0e1f/tokens \
-H "Authorization: Bearer tk_live_abc123..." \
-H "Content-Type: application/json" \
-d '{
"name": "CI pipeline token",
"kind": "agent",
"expires_in_seconds": 2592000
}'
```
```python Python theme={"dark"}
import requests
agent = "7c4d2e9f-1a3b-4c6d-8e0f-2a4b6c8d0e1f"
resp = requests.post(
f"https://api.knoxcall.com/v1/ai-gateway/agents/{agent}/tokens",
headers={"Authorization": "Bearer tk_live_abc123..."},
json={"name": "CI pipeline token", "expires_in_seconds": 2592000},
)
token = resp.json()["data"]["token"] # shown only once
```
**Response**
```json theme={"dark"}
{
"data": {
"id": "b1a2c3d4-e5f6-4789-abcd-1234567890ef",
"name": "CI pipeline token",
"kind": "agent",
"prefix": "kc_live_a_a4",
"token": "kc_live_a_a4b2...",
"dpop_required": false,
"expires_at": "2026-08-05T12:00:00.000Z"
},
"meta": {
"request_id": "0d5b2a9e-1f3c-4a7d-8e2b-6c9a1f4d7e35",
"note": "Save this token now — it will not be shown again."
}
}
```
`expires_at` is `null` when `expires_in_seconds` is omitted. If `dpop_required` is `true` but `dpop_jkt` is missing, the request returns `400 validation` — a DPoP-bound token is unusable without the key thumbprint. See [Tokens & DPoP](/ai-gateway/tokens-and-dpop) for generating the thumbprint and sending DPoP proofs.
## Revoke a token
```http theme={"dark"}
DELETE /v1/ai-gateway/agents/{agentId}/tokens/{tokenId}
```
Immediately revokes the token. In-flight requests that have already passed auth complete; no new requests are accepted. Requires the `write` capability. Returns `404 not_found` if the token does not exist or is already revoked.
```bash theme={"dark"}
curl -X DELETE \
https://api.knoxcall.com/v1/ai-gateway/agents/7c4d2e9f-1a3b-4c6d-8e0f-2a4b6c8d0e1f/tokens/b1a2c3d4-e5f6-4789-abcd-1234567890ef \
-H "Authorization: Bearer tk_live_abc123..."
```
**Response**
```json theme={"dark"}
{
"data": {
"id": "b1a2c3d4-e5f6-4789-abcd-1234567890ef",
"revoked": true
},
"meta": {
"request_id": "0d5b2a9e-1f3c-4a7d-8e2b-6c9a1f4d7e35"
}
}
```