# Workspace Admin

## List all workspaces in the account

`$ cadenya workspace-admin list`

**get** `/v1/account/workspaces`

Lists every workspace in the account, optionally including archived ones. Admin only.

### Parameters

- `--cursor: optional string`

  Pagination cursor from previous response

- `--include-archived: optional boolean`

  When true, archived workspaces are included in the results. Defaults to
  false (active workspaces only).

- `--limit: optional number`

  Maximum number of results to return

### Returns

- `ListAccountWorkspacesResponse: object { items, pagination }`

  - `items: optional array of Workspace`

    - `metadata: object { 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: optional string`

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

      - `labels: optional map[string]`

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

    - `spec: object { description }`

      - `description: optional string`

    - `status: optional "STATUS_ENABLED" or "STATUS_DISABLED" or "STATUS_ARCHIVED"`

      Lifecycle status of the workspace. Archived workspaces reject all
      requests scoped to them. Server-populated.

      - `"STATUS_ENABLED"`

      - `"STATUS_DISABLED"`

      - `"STATUS_ARCHIVED"`

  - `pagination: optional object { nextCursor, total }`

    - `nextCursor: optional string`

    - `total: optional number`

### Example

```cli
cadenya workspace-admin list \
  --api-key 'My API Key'
```

#### 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

`$ cadenya workspace-admin create`

**post** `/v1/account/workspaces`

Creates a new workspace in the account. Admin only.

### Parameters

- `--metadata: object { name, externalId, 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.

- `--spec: object { description }`

### Returns

- `workspace: object { metadata, spec, status }`

  - `metadata: object { 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: optional string`

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

    - `labels: optional map[string]`

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

  - `spec: object { description }`

    - `description: optional string`

  - `status: optional "STATUS_ENABLED" or "STATUS_DISABLED" or "STATUS_ARCHIVED"`

    Lifecycle status of the workspace. Archived workspaces reject all
    requests scoped to them. Server-populated.

    - `"STATUS_ENABLED"`

    - `"STATUS_DISABLED"`

    - `"STATUS_ARCHIVED"`

### Example

```cli
cadenya workspace-admin create \
  --api-key 'My API Key' \
  --metadata '{name: name}' \
  --spec '{}'
```

#### 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

`$ cadenya workspace-admin retrieve`

**get** `/v1/account/workspaces/{workspaceId}`

Retrieves a workspace in the account by ID. Admin only.

### Parameters

- `--workspace-id: string`

  Workspace ID to retrieve (path).

### Returns

- `workspace: object { metadata, spec, status }`

  - `metadata: object { 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: optional string`

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

    - `labels: optional map[string]`

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

  - `spec: object { description }`

    - `description: optional string`

  - `status: optional "STATUS_ENABLED" or "STATUS_DISABLED" or "STATUS_ARCHIVED"`

    Lifecycle status of the workspace. Archived workspaces reject all
    requests scoped to them. Server-populated.

    - `"STATUS_ENABLED"`

    - `"STATUS_DISABLED"`

    - `"STATUS_ARCHIVED"`

### Example

```cli
cadenya workspace-admin retrieve \
  --api-key 'My API Key' \
  --workspace-id workspaceId
```

#### 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

`$ cadenya workspace-admin update`

**patch** `/v1/account/workspaces/{workspaceId}`

Updates a workspace's metadata (e.g. name) and spec. Admin only.

### Parameters

- `--workspace-id: string`

  Workspace ID to update (path).

- `--metadata: optional object { name, externalId, 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.

- `--spec: optional object { description }`

- `--update-mask: optional string`

  Fields to update.

### Returns

- `workspace: object { metadata, spec, status }`

  - `metadata: object { 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: optional string`

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

    - `labels: optional map[string]`

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

  - `spec: object { description }`

    - `description: optional string`

  - `status: optional "STATUS_ENABLED" or "STATUS_DISABLED" or "STATUS_ARCHIVED"`

    Lifecycle status of the workspace. Archived workspaces reject all
    requests scoped to them. Server-populated.

    - `"STATUS_ENABLED"`

    - `"STATUS_DISABLED"`

    - `"STATUS_ARCHIVED"`

### Example

```cli
cadenya workspace-admin update \
  --api-key 'My API Key' \
  --workspace-id workspaceId
```

#### 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

`$ cadenya workspace-admin archive`

**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`

  Workspace ID to archive (path).

### Example

```cli
cadenya workspace-admin archive \
  --api-key 'My API Key' \
  --workspace-id workspaceId
```

## Domain Types

### Workspace Member

- `workspace_member: object { actorId, profileId, addedAt, 2 more }`

  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: optional string`

    When the member was added to the workspace.

  - `email: optional string`

    Email address of the member's profile.

  - `name: optional string`

    Display name of the member's profile.

# Members

## List workspace members

`$ cadenya workspace-admin:members list`

**get** `/v1/account/workspaces/{workspaceId}/members`

Lists the members of a workspace. Admin only.

### Parameters

- `--workspace-id: string`

  The workspace whose members will be listed (path).

- `--cursor: optional string`

  Pagination cursor from previous response

- `--limit: optional number`

  Maximum number of results to return

### Returns

- `ListWorkspaceMembersResponse: object { items, pagination }`

  - `items: optional array of WorkspaceMember`

    - `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: optional string`

      When the member was added to the workspace.

    - `email: optional string`

      Email address of the member's profile.

    - `name: optional string`

      Display name of the member's profile.

  - `pagination: optional object { nextCursor, total }`

    - `nextCursor: optional string`

    - `total: optional number`

### Example

```cli
cadenya workspace-admin:members list \
  --api-key 'My API Key' \
  --workspace-id workspaceId
```

#### 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

`$ cadenya workspace-admin:members add`

**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`

  The workspace to add the member to (path).

- `--email: optional string`

  Email address to add (resolve-or-invite). Mutually exclusive with profile_id.

- `--profile-id: optional string`

  An existing account profile to add. Mutually exclusive with email.

### Returns

- `workspace_member: object { actorId, profileId, addedAt, 2 more }`

  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: optional string`

    When the member was added to the workspace.

  - `email: optional string`

    Email address of the member's profile.

  - `name: optional string`

    Display name of the member's profile.

### Example

```cli
cadenya workspace-admin:members add \
  --api-key 'My API Key' \
  --workspace-id workspaceId
```

#### Response

```json
{
  "actorId": "actorId",
  "profileId": "profileId",
  "addedAt": "2019-12-27T18:11:19.117Z",
  "email": "email",
  "name": "name"
}
```

## Remove a member from a workspace

`$ cadenya workspace-admin:members remove`

**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`

  The workspace to remove the member from (path).

- `--profile-id: string`

  The profile to remove from the workspace (path).

### Example

```cli
cadenya workspace-admin:members remove \
  --api-key 'My API Key' \
  --workspace-id workspaceId \
  --profile-id profileId
```

# Profiles

## Search account profiles

`$ cadenya workspace-admin:profiles list`

**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: optional string`

  Pagination cursor from previous response

- `--limit: optional number`

  Maximum number of results to return

- `--query: optional string`

  Free-form search over profile name and email. Case-insensitive substring
  match; empty returns all profiles.

### Returns

- `ListProfilesResponse: object { items, pagination }`

  - `items: optional array of Profile`

    - `metadata: object { 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: optional string`

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

      - `labels: optional map[string]`

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

    - `spec: object { type, email, name }`

      Configuration for a profile.

      - `type: "PROFILE_TYPE_UNSPECIFIED" or "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "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: optional string`

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

      - `name: optional string`

        Display name (e.g., "Bobby Tables").

  - `pagination: optional object { nextCursor, total }`

    - `nextCursor: optional string`

    - `total: optional number`

### Example

```cli
cadenya workspace-admin:profiles list \
  --api-key 'My API Key'
```

#### 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
  }
}
```