Phantom tokens

A phantom token is the short-lived capability token your application presents on the data plane 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 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_<env>_<kind>_<random>_<crc>, 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

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.

curl "https://api.knoxcall.com/v1/ai-gateway/agents/7c4d2e9f-1a3b-4c6d-8e0f-2a4b6c8d0e1f/tokens" \
  -H "Authorization: Bearer tk_live_abc123..."

Response

{
  "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

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-<timestamp>`.
`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.

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
  }'

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

{
  "data": {
    "id": "b1a2c3d4-e5f6-4789-abcd-1234567890ef",
    "name": "CI pipeline token",
    "kind": "agent",
    "prefix": "kc_live_a_a4",
    "token": "kc_live_a_a4b2...<shown once>",
    "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 for generating the thumbprint and sending DPoP proofs.

Revoke a token

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.

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

{
  "data": {
    "id": "b1a2c3d4-e5f6-4789-abcd-1234567890ef",
    "revoked": true
  },
  "meta": {
    "request_id": "0d5b2a9e-1f3c-4a7d-8e2b-6c9a1f4d7e35"
  }
}

Overview

Routes

Secrets

Clients

Environments

API Keys

Webhooks

Ephemeral Proxy

AI Gateway

Audit Logs

Account

Tenant KMS

Secret Store Migrations

Tokens (v1)

Phantom tokens

Token format and environment

List tokens

Mint a token

Revoke a token

​Phantom tokens

​Token format and environment

​List tokens

​Mint a token

​Revoke a token

Phantom tokens

Token format and environment

List tokens

Mint a token

Revoke a token