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
client.apiKeys.list(APIKeyListParams { bundleKey, cursor, includeInfo, 4 more } query?, RequestOptionsoptions?): CursorPagination<APIKey { metadata, spec, info } >
GET/v1/account/api_keys
Create a new API key
client.apiKeys.create(APIKeyCreateParams { metadata, spec, initialWorkspaceIds } body, RequestOptionsoptions?): APIKey { metadata, spec, info }
POST/v1/account/api_keys
Get an API key by ID
client.apiKeys.retrieve(stringid, RequestOptionsoptions?): APIKey { metadata, spec, info }
GET/v1/account/api_keys/{id}
Delete an API key
client.apiKeys.delete(stringid, RequestOptionsoptions?): void
DELETE/v1/account/api_keys/{id}
Update an API key
client.apiKeys.update(stringid, APIKeyUpdateParams { metadata, spec, updateMask } body, RequestOptionsoptions?): APIKey { metadata, spec, info }
PATCH/v1/account/api_keys/{id}
Rotate an API key
client.apiKeys.rotate(stringid, RequestOptionsoptions?): APIKey { metadata, spec, info }
PUT/v1/account/api_keys/{id}/rotate
ModelsExpand Collapse
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, 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?: string

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

labels?: Record<string, 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?: 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, workspacesPreview, workspacesTotal }
createdBy?: 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?: string

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

labels?: Record<string, 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”).

workspacesPreview?: 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).

workspacesTotal?: number

Total number of workspaces this key has access to.

formatint32
APIKeyInfo { createdBy, workspacesPreview, workspacesTotal }
createdBy?: 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?: string

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

labels?: Record<string, 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”).

workspacesPreview?: 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).

workspacesTotal?: number

Total number of workspaces this key has access to.

formatint32
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?: 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
client.apiKeys.access.add(stringid, AccessAddParams { workspaceId } body, RequestOptionsoptions?): APIKey { metadata, spec, info }
POST/v1/account/api_keys/{id}/workspaces
Revoke an API key's access to a workspace
client.apiKeys.access.remove(stringworkspaceID, AccessRemoveParams { id } params, RequestOptionsoptions?): void
DELETE/v1/account/api_keys/{id}/workspaces/{workspaceId}
List the workspaces an API key has access to
client.apiKeys.access.list(stringid, AccessListParams { cursor, limit } query?, RequestOptionsoptions?): CursorPagination<Workspace { metadata, spec, status } >
GET/v1/account/api_keys/{id}/workspaces