---
title: "Update an API key"
method: PATCH
path: "/v1/account/api_keys/{id}"
tags: ["APIKeyService", "API Keys"]
---

# Update an API key

`PATCH /v1/account/api_keys/{id}`

Updates an API key.

## Path parameters

- `id` string, required

## Request body

- UpdateAPIKeyRequest
  - `id` string — The API key to update.
  - `metadata` UpdateAccountResourceMetadata — UpdateAccountResourceMetadata contains the user-provided fields for updating an account-scoped resource. Read-only fields (id, account_id, profile_id) are excluded since they are set by the server.
    - `name` string, required — Human-readable name for the resource (e.g., "Production API Key", "Staging Workspace")
    - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system)
    - `labels` object — Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"}
  - `spec` APIKeySpec — Configuration for an API key.
    - `token` string — The bearer token used to authenticate as this API key. Returned only on creation and rotation; subsequent reads omit this field.
    - `description` string — Free-form description of what this API key is used for.
    - `permissions` string[] — Permissions granted to this key. Each entry is a colon-separated verb:resource string (e.g. "manage:agents"). Currently has no enforced effect; reserved for future fine-grained authorization.
    - `system` boolean — True when this key is managed by the system (e.g. the auto-provisioned global account key). System keys cannot be deleted but can be rotated.
  - `updateMask` string, field-mask — Fields to update.

## Response `200`

OK

- APIKey — An API key for the account. Use workspace-association RPCs to grant the key access to specific workspaces; a key with zero workspaces is valid but cannot access workspace-scoped resources.
  - `metadata` AccountResourceMetadata, required — AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.
    - `id` string, required — Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")
    - `accountId` string, required — Account this resource belongs to for multi-tenant isolation (prefixed ULID)
    - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly
    - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system)
    - `labels` object — Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"}
    - `profileId` string, required
  - `spec` APIKeySpec, required — Configuration for an API key.
    - `token` string — The bearer token used to authenticate as this API key. Returned only on creation and rotation; subsequent reads omit this field.
    - `description` string — Free-form description of what this API key is used for.
    - `permissions` string[] — Permissions granted to this key. Each entry is a colon-separated verb:resource string (e.g. "manage:agents"). Currently has no enforced effect; reserved for future fine-grained authorization.
    - `system` boolean — True when this key is managed by the system (e.g. the auto-provisioned global account key). System keys cannot be deleted but can be rotated.
  - `info` APIKeyInfo
    - `createdBy` Profile — A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces.
      - `metadata` AccountResourceMetadata, required — AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.
        - `id` string, required — Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")
        - `accountId` string, required — Account this resource belongs to for multi-tenant isolation (prefixed ULID)
        - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly
        - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system)
        - `labels` object — Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"}
        - `profileId` string, required
      - `spec` ProfileSpec, required — Configuration for a profile.
        - `email` string — Email address of the profile. Required and unique within an account for user profiles.
        - `name` string — Display name (e.g., "Bobby Tables").
        - `type` 'PROFILE_TYPE_UNSPECIFIED' | 'PROFILE_TYPE_USER' | 'PROFILE_TYPE_API_KEY' | 'PROFILE_TYPE_SYSTEM', enum, required — Whether this profile represents a human user, an API key, or a system principal.
    - `workspacesPreview` BareMetadata[] — Up to a small number of workspaces this key has access to, intended for display ("Workspace 1, Workspace 2, and 4 more"). Use ListAPIKeyWorkspaces for the full paginated list.
      - `id` string
      - `name` string — Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks).
    - `workspacesTotal` integer — Total number of workspaces this key has access to.

## Other responses

- `default` — Default error response

## Changes

- **2026-06-05** `0702cb021b66` — 1 warning
  - added the new `PROFILE_TYPE_UNSPECIFIED` enum value to the `info/createdBy/allOf[#/components/schemas/Profile]/spec/type` response property for the response status `200`

[Change history](https://skmtc.dev/cadenya/apis/cadenya-api/changes/v1/account/api_keys/:id/patch.md)

---

[API](https://skmtc.dev/cadenya/apis/cadenya-api.md) · [All operations](https://skmtc.dev/cadenya/apis/cadenya-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cadenya/cadenya-api/revisions/ea07a25ab5da/schema)