Gateway keys and workload identity

Choose the credential by who is calling:

Gateway keys

A gateway key is an API key that can call the gateway and nothing else: it holds only models:read. Its secret is shown once, when it is created or rotated. The console page is AI Gateway > Gateway keys.

curl -sS -X POST "$KEYSTONE_URL/api/v1/models/gateway-keys" \
  -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
  -d '{"name": "support-bot", "scope_kind": "project", "scope_id": "'$PROJECT_ID'"}'

Rotate and revoke

POST /api/v1/models/gateway-keys/{id}/rotate with {"overlap_seconds": 3600} issues a new secret and lets the current one keep working for the overlap (0 to 604800 seconds, default 3600). The key's id, budgets, rate limits and analytics continue. POST .../revoke revokes every credential of the key at once.

At request time a revoked or expired key answers 401, and a key whose team, project or user no longer exists answers 403 key_scope_unavailable.

Routes

Every write is audited (models.gateway_key.*) without the secret.

Per-key analytics

GET /api/v1/models/gateway-keys/{id}/analytics?from=&to=&bucket=hour (or day) reports a key's requests, errors, input and output tokens and cost over time, per model and per outcome. Hour buckets cover at most 31 days, day buckets 92. Requests refused before the budget step (authentication, the key's own limits, DLP, a rate limit) are in the request log and the audit trail, not here.

Workload identity

A workload identity trust lets a workload exchange a credential it already has for a short-lived gateway key, so no static secret is deployed. The console page is AI Gateway > Workload identity.

Rules map workloads to what they get. The first enabled rule whose every match entry matches one of the claim's values (* matches any run of characters) decides the issued key's scope_kind, scope_id, allowed_models, allowed_routes and metadata. A workload no rule matches is refused. An OIDC rule needs at least one claim condition.

The exchange

The exchange needs no Govern credential; the identity id names the trust.

curl -sS -X POST "$KEYSTONE_URL/api/v1/models/gateway/identity/token" \
  -H 'Content-Type: application/json' \
  -d '{"identity_id": "'$IDENTITY_ID'",
       "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
       "subject_token": "'"$(cat /var/run/secrets/tokens/gateway)"'",
       "subject_token_type": "urn:ietf:params:oauth:token-type:jwt"}'

The answer holds access_token (a nia_ key), expires_in (60 to 3600 seconds, default 900), gateway_key_id, the scope and the rule that matched. The exchange also accepts an RFC 8693 form, and an agent's client_id and client_secret (or HTTP Basic).

Every refusal answers 400 invalid_grant without saying why. The reason is in the organisation's audit trail (models.gateway_identity.exchange, outcome failure), and every issued key is audited too. Issued keys are listed with kind=workload and purged a week after they expire.

Gateway tokens for coding tools

Coding tools send model requests as the person using them, with a short-lived gateway token instead of a long-lived key.

• A token starts with nigw_, lives at most one hour (5 to 60 minutes may be asked for), and is bound to the person's session or enrolled device.
• It is accepted only on the gateway's client endpoints under /api/v1/models/gateway/v1/; anywhere else it is refused with 401 gateway_token_route.
• It carries the person's current permissions capped to models:read.
• Signing out of the session, retiring or reassigning the device, suspending the person or revoking the token with POST /api/v1/auth/token/revoke ends it.

Both need the person to hold models:read. Each token issued, and each refused mint, is audited as models.gateway_token.issued.

People get a token from the command line:

keystone-cli token models [--tool T] [--ttl D] [--device] [--json] [--no-cache]

With KEYSTONE_TOKEN set it mints for the person; without it, or with --device, for the enrolled device. It caches the token per user until five minutes before expiry. Administrators distribute the keystone-cli binary; Govern publishes no download of it.

The console page Models > Connect a coding tool shows the configuration for each tool and mints a token for tools that take a pasted key. Per-tool steps are on the tool pages under Third-party AI coding tools.

Authorizers

Authorizers decide who may call the gateway per route, like an API gateway's authorizers. The console page is AI Gateway > Authorizers.

Any type can also require a client certificate from a truststore (mtls.ca_pem) and HMAC-signed requests (signing, with the X-Keystone-Signature header). Traffic admitted without a Govern credential runs as the authorizer's own usage plan: its scope, models, budgets and rate limits.

PUT /api/v1/models/gateway-authorization sets the default authorizer and per-route overrides by endpoint id. On the in-server paths callers always hold a Govern credential, so the route's extra requirements (truststore, signed requests) still apply whatever the type. A route's authorizer is the only authentication on the public account edge, /api/v1/models/edge/{org}/....

Every write and every test is audited (models.gateway_authorizer.*, models.gateway_authorization.put).

Provider-native passthrough

Clients pinned to a provider's own API can use POST /api/v1/models/gateway/anthropic/v1/messages and POST /api/v1/models/gateway/openai/v1/chat/completions (also /v1/completions, /v1/embeddings, /v1/responses). They run through the same pipeline, reach only that provider's connections, and answer 403 passthrough_disabled until an administrator turns them on:

PUT /api/v1/models/gateway-passthrough   (models:admin)
{"enabled": true, "anthropic_betas": [...], "openai_betas": [...]}

Beta values not listed are dropped, never forwarded. Beta families that make the provider act on its own (mcp-client, code-execution, skills, files-api, web-fetch) are refused on every path.