# Workspace settings

The workspace’s settings and the connector secrets form. 2 routes, from the API’s own OpenAPI document.

URL: https://docs.qaldy.com/reference/api/settings/

2 routes. Every path starts at `https://cloud-api.qaldy.com`. Sign-in, tokens, errors and limits are on the [overview](https://docs.qaldy.com/reference/api/).

## Routes

| Method | Path | What it does |
|---|---|---|
| [[POST]] | [`/​v1/​workspaces/​{ws}/​connectors`](#post-v1-workspaces-ws-connectors) | Connect a service: the secret is sealed to the gate and never returned (admins) |
| [[GET]] | [`/​v1/​workspaces/​{ws}/​settings`](#get-v1-workspaces-ws-settings) | Workspace profile, policy, members, teams and connectors |

## Reference

### [[POST]] `/v1/workspaces/{ws}/connectors`

Connect a service: the secret is sealed to the gate and never returned (admins).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** admin

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Request body** (`application/json`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `connectorId` | "shop" · "stripe" · "gmail" · "telegram" · "sheets" · "slack" · "kaspi" · "1c" · … | yes |  |
| `displayName` | string | yes | 1 to 60 characters |
| `secret` | string | yes | 1 to 4096 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes | at least 1 characters |
| `connectorId` | "shop" · "stripe" · "gmail" · "telegram" · "sheets" · "slack" · "kaspi" · "1c" · … | yes |  |
| `displayName` | string | yes | at least 1 characters |
| `status` | "connected" · "expired" · "error" · "disconnected" | yes |  |
| `connectedAt` | string (date-time) or null | yes |  |
| `secret` | "write-only" · "none" | yes |  |
| `keyId` | string or null | yes |  |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[GET]] `/v1/workspaces/{ws}/settings`

Workspace profile, policy, members, teams and connectors.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** member (admin sees all)

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `workspace` | object | yes |  |
| `workspace.id` | string | yes | at least 1 characters |
| `workspace.slug` | string | yes | at least 1 characters |
| `workspace.name` | string | yes | at least 1 characters |
| `workspace.profile` | "global" · "eu" · "kz-standard" · "kz-strict" | yes |  |
| `workspace.cell` | "global" · "eu" · "kz" | yes |  |
| `workspace.locale` | "en" · "ru" · "kk" | yes |  |
| `workspace.timezone` | string | yes | at least 1 characters |
| `workspace.hourlyCostMinor` | integer | yes | at least 0 |
| `workspace.currency` | "EUR" · "USD" · "KZT" | yes |  |
| `workspace.memberCount` | integer | yes | at least 0 |
| `policy` | object | yes |  |
| `policy.allowPublicLinks` | boolean | yes |  |
| `policy.allowGuests` | boolean |  |  |
| `policy.allowedConnectors` | "shop" · "stripe" · "gmail" · "telegram" · "sheets" · "slack" · "kaspi" · "1c" · …[] or null | yes |  |
| `policy.allowedModelProviders` | "anthropic" · "openai" · "google" · "open-weight-global" · "open-weight-eu" · "open-weight-kz"[] or null | yes |  |
| `policy.retentionDays` | integer or null | yes | 1 to 3650 |
| `policy.defaultSharing` | "private" · "team" · "workspace" | yes |  |
| `policy.domainJoin` | object or null |  |  |
| `policy.flow` | object |  |  |
| `members` | object[] | yes |  |
| `members[].user` | object | yes |  |
| `members[].role` | "owner" · "admin" · "builder" · "member" · "viewer" | yes |  |
| `members[].teamId` | string or null | yes |  |
| `members[].online` | boolean | yes |  |
| `teams` | object[] | yes |  |
| `teams[].id` | string | yes | at least 1 characters |
| `teams[].name` | string | yes | at least 1 characters |
| `teams[].memberIds` | string[] | yes |  |
| `connectors` | object[] | yes |  |

…and 7 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).