Rename an API key
The api_keys.update operation: PATCH /api/v1/api_keys/{id} in the REST API and the api_keys_update tool in the MCP server.
/api/v1/api_keys/{id}Changes an API key's name, the label you see in the console and request logs. Nothing else about a key
changes after creation: to change its scopes, brand or mode, create a new key and revoke the old one.
Revoked keys can't be renamed.
At a glance
- REST:
PATCH /api/v1/api_keys/{id} - MCP tool:
api_keys_update - Operation ID:
api_keys.update - Scope: Organization, or one of its legal entities or brands
- Permission:
keys:admin - Risk tier:
security - Dry run: Supported (send
Ownrecord-Dry-Run: true) - Idempotency:
Idempotency-Keyoptional - Modes: Test and live
- Authentication: API key with the
keys:adminscope - Since: M1
Request
Path parameters
| Field | Type | Description |
|---|---|---|
id | key_… ID |
Body
A JSON object (Content-Type: application/json):
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes |
Response
200 OK with a JSON object:
| Field | Type | Description |
|---|---|---|
id | key_… ID | |
object | "api_key" | |
kind | one of org, entity, brand | |
livemode | boolean | |
name | string | |
prefix | string | |
scopes | array of one of 98 values, e.g. org:read, org:write, org:admin (all in the OpenAPI document) | |
status | one of active, expired, revoked | |
orgId | org_… ID | |
entityId | ent_… ID or null | |
brandId | brd_… ID or null | |
createdBy | string | |
createdAt | date-time | |
updatedAt | date-time | |
expiresAt | date-time or null | |
lastUsedAt | date-time or null | |
revokedAt | date-time or null |
Examples
Rename a key
PATCH /api/v1/api_keys/key_01m4ttwd3tesktp0hc6bpxwkpd
Authorization: Bearer or_test_…
Content-Type: application/json
{
"name": "Billing backend (eu-west)"
}
Response (200):
{
"id": "key_01m4ttwd3tesktp0hc6bpxwkpd",
"object": "api_key",
"kind": "brand",
"livemode": false,
"name": "Billing backend (eu-west)",
"prefix": "or_test_acme",
"scopes": ["customers:write", "subscriptions:write", "usage:write"],
"status": "active",
"orgId": "org_01m4ttwd3veh9apbewxheq5xh3",
"entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
"brandId": "brd_01m4ttwd3veh9apbewxheq5xh5",
"createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
"createdAt": "2026-10-13T12:00:00.000Z",
"updatedAt": "2026-10-20T09:30:00.000Z",
"expiresAt": null,
"lastUsedAt": null,
"revokedAt": null
}
Errors
| Code | HTTP status | When | What to do |
|---|---|---|---|
validation_failed | 400 | The name is empty or longer than 100 characters. | Fix the fields listed in details.issues and send the request again. |
resource_not_found | 404 | No key with this ID is visible in the scope and mode of the request. | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. |
api_key_revoked | 409 | The key is revoked. | Create a new key instead. |
version_conflict | 409 | The key changed at the same moment; retry. | Fetch the object again and retry the change. |
permission_denied | 403 | You can't manage API keys here. | Ask an organization owner or admin for a role or scope that allows this action. |
It can also return these common errors: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.