API key authentication
ai-gateway-auth-v2
Clients send the app's API key as a bearer token, and the gateway resolves the
calling app from the key. A missing or invalid key returns 401. A valid key
whose app doesn't match the {app_id} in the URL returns 403.
The policy applies per app: in an app's chain, it requires a key for that app alone. A new top-level team's policy template includes it as a locked entry—and sub-teams inherit that template by default—so apps created in the team require keys from the start.
Options
| Option | Default | What it does |
|---|---|---|
cacheTtlSeconds | 10 | How long the gateway caches a key check. 10 is also the minimum |
authHeader | Authorization | The header to read the key from |
authScheme | Bearer | The scheme prefix. Set it to "" to use the raw header value |
For clients that send x-api-key instead of a bearer token, use
{ "authHeader": "x-api-key", "authScheme": "" }.
Because key checks are cached, a revoked key can keep working until the cache expires.
A gateway without this policy is open
When an app's chain doesn't include the policy, the gateway resolves the app
from the {app_id} segment of the URL and serves the request with no key at
all. Anyone who knows the URL can spend against the app's providers and budget.
Only run an open gateway when something else, such as network isolation,
controls who can reach it.
Each app's key appears on its app page—see Apps.