Gateway API keys
Gateway keys belong to one workspace and are shown once. Charge them to departments, limit models, addresses and expiry, rotate with an overlap, or revoke.
Create a key#
Workspace owners and admins manage keys under AI Gateway › Get started. Select Create API key, give it a name such as the team or tool that will use it, and copy the key. It is shown once and stored only as a hash; if it is lost, create another one.
A key looks like al_gw_<id>.<secret>. Send it as Authorization: Bearer <key>; every endpoint except /v1/chat/completions also takes it as x-api-key. A key calls only the Gateway's /v1 endpoints, never the console or other Agent Lab products.
Keep keys out of browsers
The Gateway refuses requests that carry an Origin header (server_application_required). Call it from a server, a CLI or a script, and keep the key in an environment variable or a secret store.
Charge a key to departments#
A key's Cost attribution decides whose budget its spend counts against. With no departments, spend counts against the workspace only. With one or more, every request made with the key counts in full against each selected department's ceiling as well. A change applies to the next request; spend already recorded does not move.
Limit what a key can do#
Each of these is optional, and none is set on a new key:
| Control | What it does |
|---|---|
| Expiry | After this time the key is treated as revoked. Keys closest to expiry list first, with the days left. |
| Model allowlist | A request naming another model is refused with gateway_key_model_not_allowed. auto chooses only among the listed models. |
| Address allowlist | Up to 32 IP ranges (CIDR). A request from any other address is refused as an invalid key, and the refusal is recorded with the address. |
| Rate limits | Requests and tokens per minute for this key. See rate limits. |
| Concurrent cap | At most this many requests in flight at once. Absent by default: the Gateway accepts parallel requests the way a direct provider connection does. |
Rotate a key#
Rotate creates a new key with the same departments, allowlists and limits, and gives the old key an expiry after the overlap you choose (for example seven days). Both keys work during the overlap, so you can move each tool to the new key without a gap. The new key is shown once.
Revoke a key#
Revoke stops the key at once: the next request with it is refused with application_key_not_accepted, and requests that were already running finish. A revoked key cannot be restored.
Last used#
The key list shows when each key last sent a request to a model. Checking a key without sending a request does not count.
Manage keys from code#
A platform team can create, list and revoke keys through /v1/gateway/keys with a workspace admin's token, for example to give each developer their own key. These calls write the same audit events as the console (gateway.api_key_created, gateway.api_key_revoked), with the API as the channel. The secret is returned once, in the response to the create call.