Skip to navigation
Management APIAPI Keys

Create Key

Mint a new API key, optionally scoped to a project, capped with limit and limit_reset, restricted with allowed_models, bound to a routing policy, or set to expire with expires_at. The raw key is returned once, in the key field. Needs a payment method on file, except on the Free plan.

Authentication

AuthorizationBearer

A management key (mgmt_...), sent as Authorization: Bearer <key>. Reading /v1/routing-policies also accepts the organization’s gateway API keys; writing there needs a management key.

Request

This endpoint expects an object.
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; an empty list blocks every model.

disabledbooleanOptionalDefaults to false
Create the key disabled. A disabled key can't call the gateway.
expires_atdatetime or nullOptional

When the key stops working. Null means it never expires. Must be in the future; a value without an offset is UTC.

limitdouble or nullOptional

Spend cap in USD over the limit_reset window. Must be above 0. Omit for no cap.

limit_resetenum or nullOptional

The window the spend cap applies to, reset at midnight UTC: daily, weekly (from Monday) or monthly (from the 1st). Monthly when unset.

Allowed values:
namestring or nullOptional

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

project_idstring or nullOptionalformat: "uuid"
Project to scope the key to. A key's project can't be changed after creation.
routing_policy_idstring or nullOptional

A routing policy to bind the key to: an org-level policy or one scoped to the key’s project. Can be changed later.

Response

The created API key, with the raw key
byok_usagedoubleRead-only

The part of usage from requests that ran on the organization’s own provider credentials (BYOK).

byok_usage_dailydoubleRead-only

The BYOK part of usage_daily.

byok_usage_monthlydoubleRead-only

The BYOK part of usage_monthly.

byok_usage_weeklydoubleRead-only

The BYOK part of usage_weekly.

creator_user_idstring or nullRead-onlyformat: "uuid"
The dashboard user who created the key. Null for keys created with a management key.
disabledboolean
Whether the key is disabled. A disabled key can't call the gateway but isn't deleted.
hashstringRead-only

Stable identifier for the key: the SHA-256 hash of the raw key, as 64 hex characters. Not the secret, so it’s safe to store and log. Use it in get, update and delete calls.

keystringRead-onlyformat: "password"

The raw API key, prefixed mg_. Returned only once, in this response: store it now, it can’t be retrieved later.

labelstringRead-only

Display label: the key’s first characters, like mg_8Kx2pQr. Not the secret.

usagedoubleRead-only

Spend in USD in the current limit_reset window.

usage_dailydoubleRead-only
USD spend today.
usage_monthlydoubleRead-only
USD spend since the 1st of the month.
usage_weeklydoubleRead-only
USD spend since Monday.
allowed_modelslist of strings or nullOptional

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

budget_group_idstring or nullOptionalRead-only
The Merge for Workforce budget group the key draws down.
created_atdatetime or nullOptionalRead-only
When the key was created.
expires_atdatetime or nullOptional
When the key stops working. Null means it never expires.
limitdouble or nullOptional

Spend cap in USD over the limit_reset window. Null means no cap.

limit_remainingdouble or nullOptionalRead-only

Spend left in USD before the cap: limit minus usage, never below 0. Null when there’s no limit.

limit_resetenum or nullOptional

The window the spend cap applies to, reset at midnight UTC: daily, weekly (from Monday) or monthly (from the 1st). Monthly when unset.

Allowed values:
namestring or nullOptional
The key's name.
project_idstring or nullOptionalformat: "uuid"

Project the key is scoped to, or null for an organization-wide key. Can’t be changed after creation.

routing_policy_idstring or nullOptional
Routing policy bound to the key, if any.
updated_atdatetime or nullOptionalRead-only
When the key last changed.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error
502
Bad Gateway Error
503
Service Unavailable Error