Skip to navigation
Management APIAPI keys

Create an API key

Mint a new API key, optionally scoped to a project, capped with limit and limit_reset, or restricted with allowed_models. The raw key is returned once, in the key field.

Authentication

AuthorizationBearer

A management key (prefixed mgmt_), created on the dashboard’s API keys page under Management keys. Distinct from a regular gateway API key, and never used to call models.

Request

This endpoint expects an object.
namestring or nullOptional

A name for the key, for example customer-acme or alice@acme.com. Shown in the dashboard and usage views.

limitdouble or nullOptional
Optional spend cap in USD over the reset window.
limit_resetenumOptional

Window the spend cap resets on; defaults to monthly.

Allowed values:
project_idstring or nullOptionalformat: "uuid"

Project to scope the key to; a key’s project can’t be changed after creation.

allowed_modelslist of strings or nullOptional

Canonical provider/model IDs this key may call, where a trailing * matches by prefix; omit or send null for no restriction, and an empty list blocks every model.

Response

The created key, including the raw secret.
hashstring

Stable identifier for the key. A one-way hash, not the secret, so it is safe to store and log. Use it in get, update, and delete calls.

labelstring

Display label (the key’s public prefix, e.g. mg_8Kx2pQ). Not the secret.

disabledboolean
Whether the key is disabled. A disabled key cannot call the gateway but is not deleted.
usagedouble
Spend in USD in the current reset window.
keystring

The raw API key (prefixed mg_). Shown exactly once, at creation. Store it now; it cannot be retrieved later.

namestring or nullOptional

User-set name for the key.

limitdouble or nullOptional
Spend cap in USD over the reset window. Null means no cap.
limit_resetenumOptional
Window the spend cap resets on. Resets at midnight UTC.
Allowed values:
limit_remainingdouble or nullOptional
Remaining spend in USD before the cap. Null when no limit is set.
created_atdatetime or nullOptional
When the key was created.
project_idstring or nullOptional

Project the key is scoped to, or null for an organization-wide key.

allowed_modelslist of strings or nullOptional

Models the key may call; null means unrestricted and an empty list blocks every model.

routing_policy_idstring or nullOptional
Routing policy bound to the key, if any.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error