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(ctx, query) (*CursorPagination[APIKey], error)
GET/v1/account/api_keys
Create a new API key
client.APIKeys.New(ctx, body) (*APIKey, error)
POST/v1/account/api_keys
Get an API key by ID
client.APIKeys.Get(ctx, id) (*APIKey, error)
GET/v1/account/api_keys/{id}
Delete an API key
client.APIKeys.Delete(ctx, id) error
DELETE/v1/account/api_keys/{id}
Update an API key
client.APIKeys.Update(ctx, id, body) (*APIKey, error)
PATCH/v1/account/api_keys/{id}
Rotate an API key
client.APIKeys.Rotate(ctx, id) (*APIKey, error)
PUT/v1/account/api_keys/{id}/rotate
ModelsExpand Collapse
type APIKey struct{…}

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.

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 stringOptional

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

Labels map[string, string]Optional

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

Configuration for an API key.

Token stringOptional

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

Description stringOptional

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

Permissions []stringOptional

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 boolOptional

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 APIKeyInfoOptional
CreatedBy ProfileOptional

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.

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 stringOptional

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

Labels map[string, string]Optional

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

Configuration for a profile.

Type ProfileSpecType

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

formatenum
One of the following:
const ProfileSpecTypeProfileTypeUnspecified ProfileSpecType = "PROFILE_TYPE_UNSPECIFIED"
const ProfileSpecTypeProfileTypeUser ProfileSpecType = "PROFILE_TYPE_USER"
const ProfileSpecTypeProfileTypeAPIKey ProfileSpecType = "PROFILE_TYPE_API_KEY"
const ProfileSpecTypeProfileTypeSystem ProfileSpecType = "PROFILE_TYPE_SYSTEM"
Email stringOptional

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

Name stringOptional

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

WorkspacesPreview []BareMetadataOptional

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 stringOptional
Name stringOptional

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 int64Optional

Total number of workspaces this key has access to.

formatint32
type APIKeyInfo struct{…}
CreatedBy ProfileOptional

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.

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 stringOptional

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

Labels map[string, string]Optional

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

Configuration for a profile.

Type ProfileSpecType

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

formatenum
One of the following:
const ProfileSpecTypeProfileTypeUnspecified ProfileSpecType = "PROFILE_TYPE_UNSPECIFIED"
const ProfileSpecTypeProfileTypeUser ProfileSpecType = "PROFILE_TYPE_USER"
const ProfileSpecTypeProfileTypeAPIKey ProfileSpecType = "PROFILE_TYPE_API_KEY"
const ProfileSpecTypeProfileTypeSystem ProfileSpecType = "PROFILE_TYPE_SYSTEM"
Email stringOptional

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

Name stringOptional

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

WorkspacesPreview []BareMetadataOptional

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 stringOptional
Name stringOptional

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 int64Optional

Total number of workspaces this key has access to.

formatint32
type APIKeySpec struct{…}

Configuration for an API key.

Token stringOptional

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

Description stringOptional

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

Permissions []stringOptional

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 boolOptional

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(ctx, id, body) (*APIKey, error)
POST/v1/account/api_keys/{id}/workspaces
Revoke an API key's access to a workspace
client.APIKeys.Access.Remove(ctx, id, workspaceID) error
DELETE/v1/account/api_keys/{id}/workspaces/{workspaceId}
List the workspaces an API key has access to
client.APIKeys.Access.List(ctx, id, query) (*CursorPagination[Workspace], error)
GET/v1/account/api_keys/{id}/workspaces