Update an API key's name, IP allowlist or inbox restriction

Updates the mutable fields of the key identified by apiKeyId: its name, its allowedIps, its inboxIds restriction, or any combination.

Endpoint

PATCH https://api.dairo.app/v1/api-keys/{apiKeyId}

Updates the mutable fields of the key identified by apiKeyId: its name, its allowedIps, its inboxIds restriction, or any combination. Send at least one of the three — a request with none returns 400. Supplying allowedIps replaces the entire allowlist under the same up-to-50 IPv4/IPv6-or-CIDR validation used on create; pass an empty array to clear it and allow any IP, or omit the field to leave the current allowlist unchanged. Supplying inboxIds likewise replaces the whole inbox restriction ([] lifts it); a key that is itself pinned can only narrow a key to inboxes it holds, so it cannot widen itself or a sibling. None of the three fields is nullable here: an explicit null returns 400 rather than being silently ignored. A key's scopes and secret are immutable here, so to change granted scopes you create a replacement key and revoke the old one. Requires the keys:write scope and a key whose creator is an organization owner or admin (403 otherwise); an unknown apiKeyId, or a key outside the inboxes of a calling key that is itself pinned, returns 404, and the updated key object is returned on success.

Scope: keys:write. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

cURL

curl -X PATCH "https://api.dairo.app/v1/api-keys/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Path parameters

Name	Type	Required	Description
`apiKeyId`	string	yes	The API key's ID.

Body

Required, application/json: UpdateApiKeyRequest.

At least one of name, allowedIps or inboxIds is required. scopes is deliberately absent: scopes are immutable after mint, and revoking is DELETE on this same path. Sending either is a 400 rather than a silently-ignored no-op.

Field	Type	Required	Description
`name`	string	no	New display name. Omit to leave it unchanged; `null` is rejected with 400 rather than silently ignored.
`allowedIps`	array of string	no	Replaces the whole allowlist; it never merges. Omit the field to leave the current allowlist unchanged, or pass an empty array to clear it so the key may authenticate from any IP. Entries are IPv4/IPv6 addresses or CIDR ranges (up to 50); deny-by-default, so a correct secret from an unlisted IP is rejected with 403. Explicit `null` is rejected with 400 — unlike on create it does not mean `any IP` here, and it used to be a silently-ignored no-op.
`inboxIds`	array of string (uuid)	no	Replaces the whole per-inbox restriction; it never merges. Omit to leave it unchanged, or pass an empty array to clear it so the key may send as any inbox. A restricted key may only ever narrow to a subset of its own inboxes — it cannot unpin itself or a sibling. Explicit `null` is rejected with 400: unlike on create it does not mean `unrestricted` here, it would change nothing.

Response

200 Success. Body: application/json, ApiKey.

Field	Type	Required	Description
`object`	`"api_key"`	yes
`id`	string (uuid)	yes
`name`	string	yes
`prefix`	string	yes
`scopes`	array of string	yes
`status`	`"active"`, `"revoked"`	yes
`createdAt`	string (date-time)	yes
`lastUsedAt`	string (date-time) or null	no
`allowedIps`	array of string or null	no	The key's IP allowlist (IPv4/IPv6 addresses or CIDR ranges), or null when the key authenticates from any IP.
`inboxIds`	array of string (uuid) or null	no	The inbox ids (inboxes.id) this key may send as. Empty or null means the key is unrestricted and may send as any inbox in the project — the default, and what every key minted before this field existed has.
`environment`	`"live"`, `"test"`	no

200

{
  "object": "api_key",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Ada Lovelace",
  "prefix": "dairo_test_abc123",
  "scopes": [
    "string"
  ],
  "status": "active",
  "createdAt": "2026-10-19T09:30:00Z",
  "lastUsedAt": "2026-10-19T09:30:00Z",
  "allowedIps": [
    "string"
  ],
  "inboxIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "environment": "live"
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.

Status	Meaning
`400`	The request is malformed or a value is invalid (`invalid_request`, `invalid_domain`, `idempotency_key_mismatch`).
`401`	The API key is missing or invalid.
`403`	The key lacks the scope this endpoint needs (`scope_missing`) or may not do this (`not_permitted`).
`404`	No such resource in this account (`resource_not_found`).
`429`	Rate limit, plan limit, budget or spend cap reached (`rate_limited`, `plan_limit_reached`, `budget_exceeded`, `spend_cap_reached`).
`500`	An unexpected error; retry with backoff, then contact support (`internal_error`).