---
title: "Update an API key"
method: PATCH
path: "/v2/api-keys/{api_key_id}"
tags: ["API keys"]
---

# Update an API key

`PATCH /v2/api-keys/{api_key_id}`

Updates mutable fields of an API key: display name, status (active / disabled / revoked), permission mode and access map, project scope, and constraints (budget / rate limit / expiry). Omitted fields keep their current values.

## Path parameters

- `api_key_id` string, required

## Request body

- UpdateApiKeyRequest
  - `name` string — New name. Omit to keep current.
  - `status` 'API_KEY_STATUS_UNSPECIFIED' | 'API_KEY_STATUS_ACTIVE' | 'API_KEY_STATUS_DISABLED' | 'API_KEY_STATUS_REVOKED'
  - `permission_mode` 'PERMISSION_MODE_UNSPECIFIED' | 'PERMISSION_MODE_ALL' | 'PERMISSION_MODE_RESTRICTED' | 'PERMISSION_MODE_READ_ONLY'
  - `access` object — Replacement access map. Required when changing to `PERMISSION_MODE_RESTRICTED`; ignored otherwise. Provide an empty map to clear. See `ApiKey.access` for the full catalog of valid keys (Domain.id) and AccessLevel string values, or fetch the live catalog via the capability catalog endpoint.
  - `project_scope` ProjectScope — Project authorization scope. Single-project or all-projects. Multi-project use cases are served by minting per-project keys or by using an all-projects key with `restricted` mode.
    - `all` AllProjects
    - `single` SingleProject
      - `project_id` string, required — Project ID this API key is scoped to.
  - `expires_at` string, date-time — New expiration. Omit to keep current. Set `clear_expires_at = true` to remove an existing expiration (a zero Timestamp here would still mean "no change" because of optional semantics).
  - `clear_expires_at` boolean — Force-clear the expiration. Mutually exclusive with `expires_at`.
  - `mcp_access` McpAccess — McpAccess optionally restricts which MCP gateways an API key may reach at the data plane. It is orthogonal to permission_mode / access: the key must still hold the `mcp_gateway.execute` verb and project membership; McpAccess only narrows the reachable gateway set within that grant. Human sessions and keys without an McpAccess are unaffected. Semantics: - absent, or deny_all=false with an empty allowed_mcp_gateway_ids: no restriction — every gateway in the key's project scope is reachable. - deny_all=true: zero gateways are reachable. Wins over allowed_mcp_gateway_ids. - non-empty allowed_mcp_gateway_ids: only the listed gateway ids are reachable. Each id must look like `mcp_gateway_<ULID>`.
    - `deny_all` boolean — When true, the key is denied every MCP gateway regardless of allowed_mcp_gateway_ids.
    - `allowed_mcp_gateway_ids` string[] — Allow-list of MCP gateway ids (`mcp_gateway_<ULID>`) the key may reach. Ignored when deny_all is true. Empty (with deny_all=false) means no restriction.
    - `toolset_ids` string[] — Allow-list of MCP toolset ids (`mcp_toolset_<ULID>`) the key is bound to. When non-empty, the key sees and may call only the tools that are both exposed by the target gateway and members of the union of these toolsets. Empty means no toolset restriction.

## Response `200`

API key updated successfully.

- ApiKeyRestResponse
  - `id` string, required
  - `name` string, required
  - `workspace_id` string, required
  - `token` string, required — Raw on create/retrieve and masked in list responses.
  - `active` boolean
  - `is_legacy` boolean
  - `source` string
  - `budget` object
  - `expiration` string, date-time
  - `projects` string[]
  - `created_by_id` string, nullable
  - `updated_by_id` string, nullable
  - `created` string, date-time
  - `updated` string, date-time
  - `consumption` number
  - `token_consumption` number
  - `requests_per_minute_consumption` number
  - `owner` object
  - `project_scope` object
  - `permission_mode` string
  - `access` object
  - `token_prefix` string
  - `status` string
  - `constraints` object
  - `mcp_access` object
  - `legacy_token_family` string
  - `legacy_key_id` string
  - `last_used_at` string, date-time

---

[API](https://skmtc.net/orq-ai/apis/orq-ai-api.md) · [All operations](https://skmtc.net/orq-ai/apis/orq-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/orq-ai/orq-ai-api/versions/6a22c53a2580/schema)