> ## 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 & DPoP

> Phantom capability tokens: short-lived, agent-scoped, revocable credentials — with token kinds, IP/CIDR scoping, DPoP sender-constraint, and OIDC workload federation for CI.

# Tokens & DPoP

Your application authenticates to the gateway with a **phantom token** — a capability token minted for one agent. It is short-lived, scoped, and revocable, and it stands in for the real provider key (which never leaves the server).

## Token shape

```text theme={"dark"}
kc_<env>_<kind>_<32hex>_<crc>
```

* `env` — `live` or `sandbox` (mirrors the route's sandbox flag).
* `kind` — the capability class (below).
* The token is validated by a capability HMAC bound to your tenant master key, so a token minted for one tenant can't be replayed against another.

## Token kinds

| Kind        | Prefix        | Use                                                                                   |
| ----------- | ------------- | ------------------------------------------------------------------------------------- |
| **agent**   | `kc_live_a_…` | Full agent access — the normal application/agent credential.                          |
| **read**    | `kc_live_r_…` | Read-oriented calls.                                                                  |
| **tool**    | `kc_live_t_…` | Tool-bound access, intended to be scoped to an allowlisted tool set.                  |
| **oneshot** | `kc_live_o_…` | Single-use — atomically consumed on first use (ideal for a playground or a hand-off). |

## Scoping

A token's scope can constrain:

* **Providers** — which upstream providers the token may reach.
* **IP / CIDR** — the source ranges allowed to present the token (enforced via a shared CIDR matcher).
* **Expiry** — every token can carry a TTL; expired tokens are rejected at the edge.

Revoke a token at any time from the **Tokens tab** on the gateway detail page; revocation takes effect immediately.

## DPoP (sender-constrained tokens)

Set `dpop_required: true` on a token to make it **sender-constrained** per [RFC 9449](https://datatracker.ietf.org/doc/html/rfc9449). The client generates a key pair and sends a `DPoP` proof JWT on every request; the gateway binds the token to that key's thumbprint (`jkt`) and rejects the token if presented without a matching proof.

This means a leaked token is useless without the corresponding private key — the single most effective mitigation for the "unscoped env-var key" problem that dominates agent deployments. DPoP nonces are tracked in a durable, cross-worker store so replayed proofs are rejected even behind multiple workers.

```http theme={"dark"}
POST /v1/ai/support-bot/v1/messages
Authorization: Bearer kc_live_a_...
DPoP: eyJ0eXAiOiJkcG9wK2p3dC... 
```

## OIDC workload federation (CI without static secrets)

CI systems and workloads can exchange a short-lived OIDC **id\_token** (e.g. a GitHub Actions token) for a scoped phantom token via [RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693) token exchange, so no long-lived secret is stored in the pipeline:

```http theme={"dark"}
POST /v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=<oidc_id_token>
&subject_token_type=urn:ietf:params:oauth:token-type:id_token
```

An **OIDC binding** (configured on the agent's Federation section) pins the trusted issuer, audience, and required attribute conditions (for example, a specific repository), and mints a token only when the presented id\_token matches. Subject tokens are single-use — a replayed id\_token is rejected.

## Impossible-travel detection

Set a gateway's `geo_velocity_action` to catch a token used from two places too far apart to be the same holder (a leaked credential in use elsewhere):

* **off** (default) — no geo check.
* **warn** / **block** — classify each request's location against the token's last-used location and emit an alertable `ai_gateway.geo_velocity_anomaly` audit event (severity scaled by how implausible the travel is). These feed the token's security-events view and any compliance alert rules.

Geo-velocity is currently **detection + alerting only** — it does not auto-revoke. Automatic enforcement is deliberately deferred: an adversarial review showed that auto-revoke on this signal locks out legitimate users on geo-IP glitches far more often than it stops real theft, so hard enforcement waits for a more robust classifier. Act on the alerts via your own policy in the meantime.

The check is **fully off the hot path**: it never blocks or delays a request (fail-open on any error), skips the geo lookup entirely when the source IP is unchanged, and caches the per-gateway setting. Because the geo lookup is an external call, enable it deliberately (and pair it with a local geo database at high request volumes).

Refresh-token theft is detected separately: [OIDC federation](#oidc-workload-federation-ci-without-static-secrets) refresh rotation flags reuse of a rotated token and raises `ai_gateway.refresh_theft`. Both feeds surface on the token's security-events view.

## Mint tokens

Mint from the **Tokens tab** on the gateway detail page, or programmatically via the control-plane mint endpoint. The plaintext token is shown **once** at mint time — store it securely.