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 examples below authenticate with $TOKEN, a short-lived OAuth 2.1 access token minted there.

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 kp_<env>_<kind>_<random>_<crc>, e.g. kp_live_a_1a2b3c…. The prefix field is the first 12 characters (kp_live_a_ plus two characters), safe to display and store for identification.

The prefix changed on 2026-09-01, with no compatibility window. Phantom tokens used to be kc_-prefixed — the same family as OAuth 2.1 access tokens — and are now kp_. A token issued before that date no longer parses. Re-mint. See the changelog.

The environment segment is derived from the key you mint with — a test key mints a kp_test_… token, a live key mints a kp_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 $TOKEN"

Response

{
  "data": [
    {
      "id": "b1a2c3d4-e5f6-4789-abcd-1234567890ef",
      "name": "CI pipeline token",
      "kind": "agent",
      "prefix": "kp_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 the default of 30 days; there is no way to mint 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 $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI pipeline token",
    "kind": "agent",
    "expires_in_seconds": 2592000
  }'

import os
import requests

TOKEN = os.environ["KNOXCALL_ACCESS_TOKEN"]  # OAuth access token — see Authentication

agent = "7c4d2e9f-1a3b-4c6d-8e0f-2a4b6c8d0e1f"
resp = requests.post(
    f"https://api.knoxcall.com/v1/ai-gateway/agents/{agent}/tokens",
    headers={"Authorization": f"Bearer {TOKEN}"},
    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": "kp_live_a_a4",
    "token": "kp_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 always set: omitting expires_in_seconds gives the 30 days default rather than a permanent token. (Tokens minted before this default existed can still carry a null expires_at.) 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 $TOKEN"

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

Changelog

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