Skip to navigation
Management APIAPI Keys

Update Key

Update a key’s name, disabled state, spend limit, model allowlist, routing policy binding or expiry. Only the fields you send change; send null to remove a limit, allowlist, binding or expiry. A key’s project can’t be changed.

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.

Path parameters

key_hashstringRequired

The key’s hash from a create or list response.

Request

This endpoint expects an object.
allowed_modelslist of strings or nullOptional
Replaces the model allowlist. Send null to remove the restriction, or an empty list to block every model.
budget_group_idstring or nullOptional

Managed by Merge for Workforce; sending this field is a 400.

disabledboolean or nullOptional
Send true to disable the key, false to enable it again.
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. Send null to remove the expiry; omit it to leave the expiry unchanged.

limitdouble or nullOptional

New spend cap in USD. Omit to keep the current cap; send null to remove it.

limit_resetenum or nullOptional

New window for the spend cap: daily, weekly or monthly, reset at midnight UTC.

Allowed values:
namestring or nullOptional
New name for the key.
project_idstring or nullOptionalformat: "uuid"

Can’t be changed after creation; sending a value is a 400.

routing_policy_idstring or nullOptional
Routing policy to bind the key to. Send null to unbind it, so the key falls back to its project's or the organization's default.

Response

The updated API 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.

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