Management API keys
The Management API lets you create and administer your organization’s API keys programmatically, instead of clicking through the dashboard. Use it to issue a unique key for each customer or employee, rotate keys on a schedule, cap spend per key, and track usage per key. It is authenticated by a separate management key, so the credential that provisions keys is never one that can make model calls.
Management keys
A management key is a provisioning credential. It authenticates the Management API and nothing else.
Create one in the dashboard under API keys → Management keys. The raw key (prefixed mgmt_) is shown once at creation, so copy it then. Only a hash is stored, so it cannot be retrieved later.
A management key is scoped to one organization:
A management key returns 401 if used against the model endpoints. Keep it server-side, treat it like any other secret, and rotate it if it leaks.
The keys API
All Management API requests are relative to:
Authenticate with the management key as a bearer token on every request:
Create a key
POST /v1/keys mints a new API key and returns the raw key (prefixed mg_) exactly once. Pass an optional limit in USD and a limit_reset window to attach a spend cap.
To scope the key to a project, pass project_id with the project’s UUID. Every request made with a project API key attributes to that project automatically, so its routing policy and budget apply without any per-request configuration. The project scope is immutable after creation; to move a key to another project, create a new key.
The response is a key object. key is present only on creation:
hash is the stable identifier you use in every other call. It is a one-way hash, not the secret, so it is safe to store and log.
List keys
GET /v1/keys returns a page of the org’s keys with current usage, in a list envelope:
A page holds at most 100 keys. When has_more is true, advance offset by the page size and request again — otherwise an org with more than 100 keys silently looks like it has exactly 100.
Get, update, or delete a key
Address a single key by its hash:
GET /v1/keys/{hash}returns one key with its usagePATCH /v1/keys/{hash}updatesname,disabled,limit,limit_reset,allowed_models, orrouting_policy_idDELETE /v1/keys/{hash}revokes the key
allowed_models and routing_policy_id are read by field presence rather than by value on a PATCH: leave the field out and it is untouched, send it as null and it is cleared. project_id is the exception, since project scope is immutable, and sending it on a PATCH is rejected.
Deleting a key revokes it immediately but keeps its historical spend, so it still appears in usage reporting. To stop a key from being used without losing it, set disabled: true instead.
Restrict which models a key can call
allowed_models limits a key to a set of canonical model ids, which is the per-key access control to reach for when you hand keys to teams or to your own customers.
The rules that decide whether an entry works:
- Entries are canonical
provider/modelids. A bare name such asgpt-4ois rejected with400, because Gateway matches against the model a request resolves to rather than the string the caller sent - A single trailing
*is a prefix wildcard, soanthropic/claude-opus-*covers a family. A leading or interior*is rejected @alias/entries are rejected for the same resolution reason. Allow the models the config selects- Up to 200 entries, with duplicates collapsed silently
- An empty array denies every model, which is a useful way to park a key without deleting it. Omitting the field leaves the key unrestricted
Under a routing policy the allowlist filters rather than rejects: a restricted key on a Priority or Intelligent policy falls through to a permitted target and only returns 403 when nothing the policy can reach is permitted. On a request that pins a model, a disallowed model is a straight 403. The organization blocklist composes with this, and both are enforced on every surface, the SDK-compatible ones included.
Bind a routing policy to a key
routing_policy_id gives one key its own routing, so a workload gets a strategy without a per-request field and without a project of its own.
The binding sits below a policy named on the request and above the customer, project, and organization defaults, so a caller can still override it per request. See Using routing policies for the full order.
Rebinding does not require rotating the key, and validation happens on the write rather than on live traffic:
Send "routing_policy_id": null to unbind. POST /v1/embeddings ignores key bindings, so an embeddings call always resolves the policy from the request, the project, or the organization.
Per-key spend limits
Attach a budget to any key with limit, a dollar amount, and limit_reset, one of daily, weekly, or monthly. The gateway sums the key’s spend over the current window and rejects requests with HTTP 402 once the cap is reached. The window resets at midnight UTC.
Every key object reports usage, the spend in the current window, and limit_remaining, so you can show a customer their remaining balance or alert before they hit the cap. You can also set a spend limit when creating a key in the dashboard. For org-wide and project-level budgets, see Cost governance and savings.
Per-key usage and spend
Spend is tracked per key, which is effectively per customer or per employee since each key records who created it. The By API key tab in Usage & spend lists each key’s requests, tokens, and spend, and a per-key detail view breaks spend down by model, provider, and project.
Name keys when you create them, for example customer-acme or [email protected]. The usage view and key list show the name, which makes per-customer and per-employee tracking readable at a glance.