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
api_keys.list(**kwargs) -> CursorPagination<APIKey { metadata, spec, info } >
GET/v1/account/api_keys
Create a new API key
api_keys.create(**kwargs) -> APIKey { metadata, spec, info }
POST/v1/account/api_keys
Get an API key by ID
api_keys.retrieve(id) -> APIKey { metadata, spec, info }
GET/v1/account/api_keys/{id}
Delete an API key
api_keys.delete(id) -> void
DELETE/v1/account/api_keys/{id}
Update an API key
api_keys.update(id, **kwargs) -> APIKey { metadata, spec, info }
PATCH/v1/account/api_keys/{id}
Rotate an API key
api_keys.rotate(id) -> APIKey { metadata, spec, info }
PUT/v1/account/api_keys/{id}/rotate
ModelsExpand Collapse
class APIKey { 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, account_id, 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…”)

account_id: 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

profile_id: String
external_id: String

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

labels: Hash[Symbol, 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: 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: Array[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_: bool

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 { created_by, workspaces_preview, workspaces_total }
created_by: 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, account_id, 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…”)

account_id: 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

profile_id: String
external_id: String

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

labels: Hash[Symbol, 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 | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :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: String

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

name: String

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

workspaces_preview: Array[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: 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).

workspaces_total: Integer

Total number of workspaces this key has access to.

formatint32
class APIKeyInfo { created_by, workspaces_preview, workspaces_total }
created_by: 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, account_id, 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…”)

account_id: 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

profile_id: String
external_id: String

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

labels: Hash[Symbol, 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 | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :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: String

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

name: String

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

workspaces_preview: Array[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: 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).

workspaces_total: Integer

Total number of workspaces this key has access to.

formatint32
class APIKeySpec { token, description, permissions, system_ }

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: Array[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_: bool

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
api_keys.access.add(id, **kwargs) -> APIKey { metadata, spec, info }
POST/v1/account/api_keys/{id}/workspaces
Revoke an API key's access to a workspace
api_keys.access.remove(workspace_id, **kwargs) -> void
DELETE/v1/account/api_keys/{id}/workspaces/{workspaceId}
List the workspaces an API key has access to
api_keys.access.list(id, **kwargs) -> CursorPagination<Workspace { metadata, spec, status } >
GET/v1/account/api_keys/{id}/workspaces