# Workspace Admin ## List all workspaces in the account `workspace_admin.list(**kwargs) -> CursorPagination` **get** `/v1/account/workspaces` Lists every workspace in the account, optionally including archived ones. Admin only. ### Parameters - `cursor: String` Pagination cursor from previous response - `include_archived: bool` When true, archived workspaces are included in the results. Defaults to false (active workspaces only). - `limit: Integer` Maximum number of results to return ### Returns - `class 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...") - `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: 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 ```ruby require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") page = cadenya.workspace_admin.list puts(page) ``` #### 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 `workspace_admin.create(**kwargs) -> Workspace` **post** `/v1/account/workspaces` Creates a new workspace in the account. Admin only. ### Parameters - `metadata: Metadata{ name, external_id, labels}` 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") - `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: WorkspaceSpec` - `description: String` ### Returns - `class 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...") - `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: 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 ```ruby require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") workspace = cadenya.workspace_admin.create(metadata: {name: "name"}, spec: {}) puts(workspace) ``` #### 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 `workspace_admin.retrieve(workspace_id) -> Workspace` **get** `/v1/account/workspaces/{workspaceId}` Retrieves a workspace in the account by ID. Admin only. ### Parameters - `workspace_id: String` ### Returns - `class 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...") - `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: 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 ```ruby require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") workspace = cadenya.workspace_admin.retrieve("workspaceId") puts(workspace) ``` #### 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 `workspace_admin.update(workspace_id, **kwargs) -> Workspace` **patch** `/v1/account/workspaces/{workspaceId}` Updates a workspace's metadata (e.g. name) and spec. Admin only. ### Parameters - `workspace_id: String` - `metadata: Metadata{ name, external_id, labels}` 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") - `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: WorkspaceSpec` - `description: String` - `update_mask: String` Fields to update. ### Returns - `class 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...") - `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: 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 ```ruby require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") workspace = cadenya.workspace_admin.update("workspaceId") puts(workspace) ``` #### 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 `workspace_admin.archive(workspace_id) -> 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 - `workspace_id: String` ### Example ```ruby require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") result = cadenya.workspace_admin.archive("workspaceId") puts(result) ``` ## Domain Types ### Workspace Member - `class 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. - `actor_id: String` The actor row linking the profile to the workspace (the junction record). - `profile_id: String` The account profile that has access to the workspace. - `added_at: Time` 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 `workspace_admin.members.list(workspace_id, **kwargs) -> CursorPagination` **get** `/v1/account/workspaces/{workspaceId}/members` Lists the members of a workspace. Admin only. ### Parameters - `workspace_id: String` - `cursor: String` Pagination cursor from previous response - `limit: Integer` Maximum number of results to return ### Returns - `class 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. - `actor_id: String` The actor row linking the profile to the workspace (the junction record). - `profile_id: String` The account profile that has access to the workspace. - `added_at: Time` 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 ```ruby require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") page = cadenya.workspace_admin.members.list("workspaceId") puts(page) ``` #### 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 `workspace_admin.members.add(workspace_id, **kwargs) -> 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 - `workspace_id: String` - `email: String` Email address to add (resolve-or-invite). Mutually exclusive with profile_id. - `profile_id: String` An existing account profile to add. Mutually exclusive with email. ### Returns - `class 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. - `actor_id: String` The actor row linking the profile to the workspace (the junction record). - `profile_id: String` The account profile that has access to the workspace. - `added_at: Time` 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 ```ruby require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") workspace_member = cadenya.workspace_admin.members.add("workspaceId") puts(workspace_member) ``` #### Response ```json { "actorId": "actorId", "profileId": "profileId", "addedAt": "2019-12-27T18:11:19.117Z", "email": "email", "name": "name" } ``` ## Remove a member from a workspace `workspace_admin.members.remove(profile_id, **kwargs) -> 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 - `workspace_id: String` - `profile_id: String` ### Example ```ruby require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") result = cadenya.workspace_admin.members.remove("profileId", workspace_id: "workspaceId") puts(result) ``` # Profiles ## Search account profiles `workspace_admin.profiles.list(**kwargs) -> 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 - `cursor: String` Pagination cursor from previous response - `limit: Integer` 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 - `class 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...") - `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` 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 ```ruby require "cadenya" cadenya = Cadenya::Client.new(api_key: "My API Key") page = cadenya.workspace_admin.profiles.list puts(page) ``` #### 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 } } ```