# Access ## Grant an API key access to a workspace `client.apiKeys.access.add(stringid, AccessAddParamsbody, RequestOptionsoptions?): APIKey` **post** `/v1/account/api_keys/{id}/workspaces` Grants this API key access to the specified workspace. Idempotent — adding an already-associated workspace is a no-op. Returns the updated API key with refreshed workspace preview and total. ### Parameters - `id: string` - `body: AccessAddParams` - `workspaceId?: string` The workspace to grant access to. ### Returns - `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` 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` 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?: Array` 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` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `spec: ProfileSpec` 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. - `"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` 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. ### Example ```typescript import Cadenya from '@cadenya/cadenya'; const client = new Cadenya({ apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted }); const apiKey = await client.apiKeys.access.add('id'); console.log(apiKey.metadata); ``` #### Response ```json { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "token": "token", "description": "description", "permissions": [ "string" ], "system": true }, "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_UNSPECIFIED", "email": "email", "name": "name" } }, "workspacesPreview": [ { "id": "id", "name": "name" } ], "workspacesTotal": 0 } } ``` ## Revoke an API key's access to a workspace `client.apiKeys.access.remove(stringworkspaceID, AccessRemoveParamsparams, RequestOptionsoptions?): void` **delete** `/v1/account/api_keys/{id}/workspaces/{workspaceId}` Revokes this API key's access to the specified workspace. Idempotent. A key may have zero workspaces and remains valid. ### Parameters - `workspaceID: string` - `params: AccessRemoveParams` - `id: string` The API key losing workspace access (path). ### Example ```typescript import Cadenya from '@cadenya/cadenya'; const client = new Cadenya({ apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted }); await client.apiKeys.access.remove('workspaceId', { id: 'id' }); ``` ## List the workspaces an API key has access to `client.apiKeys.access.list(stringid, AccessListParamsquery?, RequestOptionsoptions?): CursorPagination` **get** `/v1/account/api_keys/{id}/workspaces` Lists the workspaces this API key has access to. Cursor-paginated. ### Parameters - `id: string` - `query: AccessListParams` - `cursor?: string` Pagination cursor from previous response. - `limit?: number` Maximum number of results to return. ### Returns - `Workspace` - `metadata: AccountResourceMetadata` 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` Arbitrary key-value pairs for categorization and filtering Examples: {"environment": "production", "team": "platform", "version": "v2"} - `spec: WorkspaceSpec` - `description?: string` - `status?: "STATUS_ENABLED" | "STATUS_DISABLED" | "STATUS_ARCHIVED"` Lifecycle status of the workspace. Archived workspaces reject all requests scoped to them. Server-populated. - `"STATUS_ENABLED"` - `"STATUS_DISABLED"` - `"STATUS_ARCHIVED"` ### Example ```typescript import Cadenya from '@cadenya/cadenya'; const client = new Cadenya({ apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const workspace of client.apiKeys.access.list('id')) { console.log(workspace.metadata); } ``` #### Response ```json { "items": [ { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "description": "description" }, "status": "STATUS_ENABLED" } ], "pagination": { "nextCursor": "nextCursor", "total": 0 } } ```