# Workspace Admin ## List all workspaces in the account `client.workspaceAdmin.list(WorkspaceAdminListParamsquery?, RequestOptionsoptions?): CursorPagination` **get** `/v1/account/workspaces` Lists every workspace in the account, optionally including archived ones. Admin only. ### Parameters - `query: WorkspaceAdminListParams` - `cursor?: string` Pagination cursor from previous response - `includeArchived?: boolean` When true, archived workspaces are included in the results. Defaults to false (active workspaces only). - `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.workspaceAdmin.list()) { 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 } } ``` ## Create a workspace `client.workspaceAdmin.create(WorkspaceAdminCreateParamsbody, RequestOptionsoptions?): Workspace` **post** `/v1/account/workspaces` Creates a new workspace in the account. Admin only. ### Parameters - `body: WorkspaceAdminCreateParams` - `metadata: Metadata` CreateAccountResourceMetadata contains the user-provided fields for creating an account-scoped resource. Read-only fields (id, account_id, profile_id) are excluded since they are set by the server. - `name: string` Human-readable name for the resource (e.g., "Production API Key", "Staging Workspace") - `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` ### 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 }); const workspace = await client.workspaceAdmin.create({ metadata: { name: 'name' }, spec: {}, }); console.log(workspace.metadata); ``` #### Response ```json { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "description": "description" }, "status": "STATUS_ENABLED" } ``` ## Get a workspace by ID `client.workspaceAdmin.retrieve(stringworkspaceID, RequestOptionsoptions?): Workspace` **get** `/v1/account/workspaces/{workspaceId}` Retrieves a workspace in the account by ID. Admin only. ### Parameters - `workspaceID: string` ### 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 }); const workspace = await client.workspaceAdmin.retrieve('workspaceId'); console.log(workspace.metadata); ``` #### Response ```json { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "description": "description" }, "status": "STATUS_ENABLED" } ``` ## Update a workspace `client.workspaceAdmin.update(stringworkspaceID, WorkspaceAdminUpdateParamsbody, RequestOptionsoptions?): Workspace` **patch** `/v1/account/workspaces/{workspaceId}` Updates a workspace's metadata (e.g. name) and spec. Admin only. ### Parameters - `workspaceID: string` - `body: WorkspaceAdminUpdateParams` - `metadata?: Metadata` UpdateAccountResourceMetadata contains the user-provided fields for updating an account-scoped resource. Read-only fields (id, account_id, profile_id) are excluded since they are set by the server. - `name: string` Human-readable name for the resource (e.g., "Production API Key", "Staging Workspace") - `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` - `updateMask?: string` Fields to update. ### 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 }); const workspace = await client.workspaceAdmin.update('workspaceId'); console.log(workspace.metadata); ``` #### Response ```json { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "description": "description" }, "status": "STATUS_ENABLED" } ``` ## Archive a workspace `client.workspaceAdmin.archive(stringworkspaceID, RequestOptionsoptions?): void` **delete** `/v1/account/workspaces/{workspaceId}` Archives a workspace (soft delete). The workspace is retained, but any subsequent request scoped to it returns a permission error. Archiving the account's last active (non-archived) workspace is not allowed and returns FailedPrecondition. Admin only. ### Parameters - `workspaceID: string` ### 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.workspaceAdmin.archive('workspaceId'); ``` ## Domain Types ### Workspace Member - `WorkspaceMember` A member of a workspace: the profile granted access plus the actor row that links it to the workspace. Returned by member list/add operations. - `actorId: string` The actor row linking the profile to the workspace (the junction record). - `profileId: string` The account profile that has access to the workspace. - `addedAt?: string` When the member was added to the workspace. - `email?: string` Email address of the member's profile. - `name?: string` Display name of the member's profile. # Members ## List workspace members `client.workspaceAdmin.members.list(stringworkspaceID, MemberListParamsquery?, RequestOptionsoptions?): CursorPagination` **get** `/v1/account/workspaces/{workspaceId}/members` Lists the members of a workspace. Admin only. ### Parameters - `workspaceID: string` - `query: MemberListParams` - `cursor?: string` Pagination cursor from previous response - `limit?: number` Maximum number of results to return ### Returns - `WorkspaceMember` A member of a workspace: the profile granted access plus the actor row that links it to the workspace. Returned by member list/add operations. - `actorId: string` The actor row linking the profile to the workspace (the junction record). - `profileId: string` The account profile that has access to the workspace. - `addedAt?: string` When the member was added to the workspace. - `email?: string` Email address of the member's profile. - `name?: string` Display name of the member's profile. ### 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 workspaceMember of client.workspaceAdmin.members.list('workspaceId')) { console.log(workspaceMember.actorId); } ``` #### Response ```json { "items": [ { "actorId": "actorId", "profileId": "profileId", "addedAt": "2019-12-27T18:11:19.117Z", "email": "email", "name": "name" } ], "pagination": { "nextCursor": "nextCursor", "total": 0 } } ``` ## Add a member to a workspace `client.workspaceAdmin.members.add(stringworkspaceID, MemberAddParamsbody, RequestOptionsoptions?): WorkspaceMember` **post** `/v1/account/workspaces/{workspaceId}/members` Grants a profile access to the workspace by creating (or reactivating) the actor that links the profile to the workspace. Accepts either an existing profile_id or an email to resolve-or-invite. Idempotent for an already-active member. Admin only. ### Parameters - `workspaceID: string` - `body: MemberAddParams` - `email?: string` Email address to add (resolve-or-invite). Mutually exclusive with profile_id. - `profileId?: string` An existing account profile to add. Mutually exclusive with email. ### Returns - `WorkspaceMember` A member of a workspace: the profile granted access plus the actor row that links it to the workspace. Returned by member list/add operations. - `actorId: string` The actor row linking the profile to the workspace (the junction record). - `profileId: string` The account profile that has access to the workspace. - `addedAt?: string` When the member was added to the workspace. - `email?: string` Email address of the member's profile. - `name?: string` Display name of the member's profile. ### 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 workspaceMember = await client.workspaceAdmin.members.add('workspaceId'); console.log(workspaceMember.actorId); ``` #### Response ```json { "actorId": "actorId", "profileId": "profileId", "addedAt": "2019-12-27T18:11:19.117Z", "email": "email", "name": "name" } ``` ## Remove a member from a workspace `client.workspaceAdmin.members.remove(stringprofileID, MemberRemoveParamsparams, RequestOptionsoptions?): void` **delete** `/v1/account/workspaces/{workspaceId}/members/{profileId}` Revokes a member's access by deactivating their actor; the member is immediately cut off. The underlying profile is not deleted. Admin only. ### Parameters - `profileID: string` - `params: MemberRemoveParams` - `workspaceId: string` The workspace to remove the member from (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.workspaceAdmin.members.remove('profileId', { workspaceId: 'workspaceId' }); ``` # Profiles ## Search account profiles `client.workspaceAdmin.profiles.list(ProfileListParamsquery?, RequestOptionsoptions?): CursorPagination` **get** `/v1/account/profiles` Searches the account's profiles for a member picker, with free-form name/email search and an optional type filter. Account-scoped; admin only. ### Parameters - `query: ProfileListParams` - `cursor?: string` Pagination cursor from previous response - `limit?: number` Maximum number of results to return - `query?: string` Free-form search over profile name and email. Case-insensitive substring match; empty returns all profiles. ### Returns - `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. - `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: 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"). ### 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 profile of client.workspaceAdmin.profiles.list()) { console.log(profile.metadata); } ``` #### Response ```json { "items": [ { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_UNSPECIFIED", "email": "email", "name": "name" } } ], "pagination": { "nextCursor": "nextCursor", "total": 0 } } ```