Skip to content
cadenya
Get started
API Reference

API Keys

Issue, rotate, and revoke API keys for the account, and grant or revoke each key’s access to individual workspaces.

List API keys
GET/v1/account/api_keys
Create a new API key
POST/v1/account/api_keys
Get an API key by ID
GET/v1/account/api_keys/{id}
Delete an API key
DELETE/v1/account/api_keys/{id}
Update an API key
PATCH/v1/account/api_keys/{id}
Rotate an API key
PUT/v1/account/api_keys/{id}/rotate
ModelsExpand Collapse
APIKey object { metadata, spec, info }

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 { id, accountId, name, 3 more }

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

id: string

Unique identifier for the resource (prefixed ULID, e.g., “apikey_01HXK…”)

accountId: string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

name: string

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profileId: string
externalId: optional string

External ID for the resource (e.g., a workflow ID from an external system)

labels: optional map[string]

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

spec: APIKeySpec { token, description, permissions, system }

Configuration for an API key.

token: optional string

The bearer token used to authenticate as this API key. Returned only on creation and rotation; subsequent reads omit this field.

description: optional string

Free-form description of what this API key is used for.

permissions: optional array of 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: optional 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: optional APIKeyInfo { createdBy, workspacesPreview, workspacesTotal }
createdBy: optional Profile { metadata, spec }

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 { id, accountId, name, 3 more }

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

id: string

Unique identifier for the resource (prefixed ULID, e.g., “apikey_01HXK…”)

accountId: string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

name: string

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profileId: string
externalId: optional string

External ID for the resource (e.g., a workflow ID from an external system)

labels: optional map[string]

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

spec: ProfileSpec { type, email, name }

Configuration for a profile.

type: "PROFILE_TYPE_UNSPECIFIED" or "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"

Whether this profile represents a human user, an API key, or a system principal.

formatenum
One of the following:
"PROFILE_TYPE_UNSPECIFIED"
"PROFILE_TYPE_USER"
"PROFILE_TYPE_API_KEY"
"PROFILE_TYPE_SYSTEM"
email: optional string

Email address of the profile. Required and unique within an account for user profiles.

name: optional string

Display name (e.g., “Bobby Tables”).

workspacesPreview: optional array of BareMetadata { id, name }

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: optional string
name: optional 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: optional number

Total number of workspaces this key has access to.

formatint32
APIKeyInfo object { createdBy, workspacesPreview, workspacesTotal }
createdBy: optional Profile { metadata, spec }

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 { id, accountId, name, 3 more }

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

id: string

Unique identifier for the resource (prefixed ULID, e.g., “apikey_01HXK…”)

accountId: string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

name: string

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profileId: string
externalId: optional string

External ID for the resource (e.g., a workflow ID from an external system)

labels: optional map[string]

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

spec: ProfileSpec { type, email, name }

Configuration for a profile.

type: "PROFILE_TYPE_UNSPECIFIED" or "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"

Whether this profile represents a human user, an API key, or a system principal.

formatenum
One of the following:
"PROFILE_TYPE_UNSPECIFIED"
"PROFILE_TYPE_USER"
"PROFILE_TYPE_API_KEY"
"PROFILE_TYPE_SYSTEM"
email: optional string

Email address of the profile. Required and unique within an account for user profiles.

name: optional string

Display name (e.g., “Bobby Tables”).

workspacesPreview: optional array of BareMetadata { id, name }

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: optional string
name: optional 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: optional number

Total number of workspaces this key has access to.

formatint32
APIKeySpec object { token, description, permissions, system }

Configuration for an API key.

token: optional string

The bearer token used to authenticate as this API key. Returned only on creation and rotation; subsequent reads omit this field.

description: optional string

Free-form description of what this API key is used for.

permissions: optional array of 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: optional 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.

API KeysAccess

Issue, rotate, and revoke API keys for the account, and grant or revoke each key’s access to individual workspaces.

Grant an API key access to a workspace
POST/v1/account/api_keys/{id}/workspaces
Revoke an API key's access to a workspace
DELETE/v1/account/api_keys/{id}/workspaces/{workspaceId}
List the workspaces an API key has access to
GET/v1/account/api_keys/{id}/workspaces