Skip to main content

​
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

  • 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

​
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. 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.

​
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 token exchange, so no long-lived secret is stored in the pipeline:
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 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.