# Workspace Admin

## List all workspaces in the account

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

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

### Query Parameters

- `cursor: optional string`

  Pagination cursor from previous response

- `includeArchived: 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

- `items: optional array of 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: 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: WorkspaceSpec`

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

  - `nextCursor: optional string`

  - `total: optional number`

### Example

```http
curl https://api.cadenya.com/v1/account/workspaces \
    -H "Authorization: Bearer $CADENYA_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

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

Creates a new workspace in the account. Admin only.

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

  - `name: string`

    Human-readable name for the resource (e.g., "Production API Key", "Staging Workspace")

  - `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: WorkspaceSpec`

  - `description: optional string`

### Returns

- `Workspace object { metadata, spec, status }`

  - `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: 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: WorkspaceSpec`

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

```http
curl https://api.cadenya.com/v1/account/workspaces \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CADENYA_API_KEY" \
    -d '{
          "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

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

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

### Path Parameters

- `workspaceId: string`

### Returns

- `Workspace object { metadata, spec, status }`

  - `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: 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: WorkspaceSpec`

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

```http
curl https://api.cadenya.com/v1/account/workspaces/$WORKSPACE_ID \
    -H "Authorization: Bearer $CADENYA_API_KEY"
```

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

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

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

### Path Parameters

- `workspaceId: string`

### Body Parameters

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

  - `name: string`

    Human-readable name for the resource (e.g., "Production API Key", "Staging Workspace")

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

  - `description: optional string`

- `updateMask: optional string`

  Fields to update.

### Returns

- `Workspace object { metadata, spec, status }`

  - `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: 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: WorkspaceSpec`

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

```http
curl https://api.cadenya.com/v1/account/workspaces/$WORKSPACE_ID \
    -X PATCH \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CADENYA_API_KEY" \
    -d '{}'
```

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

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

### Path Parameters

- `workspaceId: string`

### Example

```http
curl https://api.cadenya.com/v1/account/workspaces/$WORKSPACE_ID \
    -X DELETE \
    -H "Authorization: Bearer $CADENYA_API_KEY"
```

## Domain Types

### Workspace Member

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

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

Lists the members of a workspace. Admin only.

### Path Parameters

- `workspaceId: string`

### Query Parameters

- `cursor: optional string`

  Pagination cursor from previous response

- `limit: optional number`

  Maximum number of results to return

### Returns

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

  - `nextCursor: optional string`

  - `total: optional number`

### Example

```http
curl https://api.cadenya.com/v1/account/workspaces/$WORKSPACE_ID/members \
    -H "Authorization: Bearer $CADENYA_API_KEY"
```

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

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

### Path Parameters

- `workspaceId: string`

### Body Parameters

- `email: optional string`

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

- `profileId: optional string`

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

### Returns

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

```http
curl https://api.cadenya.com/v1/account/workspaces/$WORKSPACE_ID/members \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CADENYA_API_KEY" \
    -d '{}'
```

#### Response

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

## Remove a member from a workspace

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

### Path Parameters

- `workspaceId: string`

- `profileId: string`

### Example

```http
curl https://api.cadenya.com/v1/account/workspaces/$WORKSPACE_ID/members/$PROFILE_ID \
    -X DELETE \
    -H "Authorization: Bearer $CADENYA_API_KEY"
```

# Profiles

## Search account profiles

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

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

- `items: optional array of Profile`

  - `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: 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: ProfileSpec`

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

  - `nextCursor: optional string`

  - `total: optional number`

### Example

```http
curl https://api.cadenya.com/v1/account/profiles \
    -H "Authorization: Bearer $CADENYA_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
  }
}
```