API Keys

How keys work#

• An API key belongs to a team, not to a person. Usage and cost are charged to that team's balance.
• One key works for every data-plane endpoint on apis.opengateway.ai: chat completions, responses, messages, embeddings, images, and decisions.
• Send it as Authorization: Bearer <key>. On /v1/messages, the Anthropic-style x-api-key header is also accepted when no Authorization header is present.
• Every request is recorded with the key that sent it, so you can filter logs and usage by key.

Any team member can create a key. Only Owners and Admins can disable, enable, delete, or restrict keys.

Create a key#

1. Open API Keys in the console.
2. Click Create new key and give it a name that says where it runs, such as prod-worker or local-dev.
3. Optionally pick Allowed models (see below).
4. Copy the key. It is shown only once.

export OPENGATEWAY_API_KEY="YOUR_API_KEY"

The Key column in the list shows a SHA-256 handle that identifies the key without revealing it. It is not the key prefix.

If the team has no available balance, a new key is created as Suspended — no balance and becomes active automatically once the team is funded.

Key statuses#

Disabling takes effect within a few seconds. Use it when you want to stop a key temporarily, for example while investigating unexpected traffic, and delete it when you are sure it is no longer needed.

If you enable a key while the team balance is zero, it moves to Suspended — no balance until you top up.

Restrict a key to specific models#

By default a key can call every model visible to its team. To narrow that down, set Allowed models when creating the key, or use Edit allowed models on an existing key and choose a subset.

• Requests for a model outside the list are rejected.
• GET /v1/models with a restricted key returns only the models that key can use.
• Changes can take up to 30 seconds to apply.
• Remove restriction returns the key to the team's full visible-model list.

Restricted keys are useful for sharing a key with a tool or contractor that should only ever call one model, such as a coding agent pinned to an UltraFast model.

Spending limits per key#

Owners and Admins can set daily, weekly, and monthly spending limits for each key, plus a monthly limit for the whole team, on the console Quota page. A limit that is switched off means unlimited.

When a limit is reached, requests return 429 with code budget_exceeded until the period resets or the limit is raised. Responses close to the limit carry an X-OG-Budget-Warn header. See Errors.

Concurrency on UltraFast models#

UltraFast models cap the number of in-flight requests per key and model. Extra requests get 429 concurrency_limit_exceeded with Retry-After. If your workload needs more parallel requests, contact support to raise the limit. See UltraFast.

Rotate a key#

1. Create a new key.
2. Deploy it to every service that used the old key.
3. Watch Logs filtered by the old key until its traffic reaches zero.
4. Disable the old key, confirm nothing breaks, then delete it.

Best practices#

• Use one key per environment (production, staging, local) and, where practical, one per service. Rotation and auditing get much simpler.
• Never commit keys or ship them in browser or mobile code. If a key leaks, disable it immediately, then rotate.
• Do not paste keys into chat, email, or issue comments. Use your secret manager.
• Name keys after where they run. prod-chat-worker beats my-key-3.

Roles and who can do what are described in Teams.