# People and roles Members, roles, access end dates, invites, joining by company domain and handing a workspace over. 11 routes, from the API’s own OpenAPI document. URL: https://docs.qaldy.com/reference/api/team/ 11 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 | |---|---|---| | [[GET]] | [`/​v1/​me/​join-suggestions`](#get-v1-me-join-suggestions) | Workspaces your verified company address can join in one click | | [[POST]] | [`/​v1/​workspaces/​{ws}/​join`](#post-v1-workspaces-ws-join) | Join a workspace whose verified company domain matches your verified address | | [[GET]] | [`/​v1/​workspaces/​{ws}/​join-domain`](#get-v1-workspaces-ws-join-domain) | The company-domain rule: which domain, whether it is verified, who may join (admins) | | [[PUT]] | [`/​v1/​workspaces/​{ws}/​join-domain`](#put-v1-workspaces-ws-join-domain) | Claim a company domain: returns the DNS record that proves it is yours (admins) | | [[PATCH]] | [`/​v1/​workspaces/​{ws}/​join-domain`](#patch-v1-workspaces-ws-join-domain) | Turn auto-join on or off and pick Member or Viewer, once verified (admins) | | [[DELETE]] | [`/​v1/​workspaces/​{ws}/​join-domain`](#delete-v1-workspaces-ws-join-domain) | Forget the company domain: nobody can join with it any more (admins) | | [[POST]] | [`/​v1/​workspaces/​{ws}/​join-domain/​verify`](#post-v1-workspaces-ws-join-domain-verify) | Look for the DNS record and, if it is there, verify the domain (admins) | | [[GET]] | [`/​v1/​workspaces/​{ws}/​members`](#get-v1-workspaces-ws-members) | Everyone in the workspace with their role, the people with most say first | | [[PATCH]] | [`/​v1/​workspaces/​{ws}/​members/​{userId}`](#patch-v1-workspaces-ws-members-userid) | Change someone's role, or the date their access ends (admins) | | [[DELETE]] | [`/​v1/​workspaces/​{ws}/​members/​{userId}`](#delete-v1-workspaces-ws-members-userid) | Remove someone (admins), or leave the workspace yourself (anyone but the last owner) | | [[POST]] | [`/​v1/​workspaces/​{ws}/​members/​{userId}/​transfer-ownership`](#post-v1-workspaces-ws-members-userid-transfer-ownership) | Hand the workspace to someone else and become an admin (the owner only) | ## Reference ### [[GET]] `/v1/me/join-suggestions` Workspaces your verified company address can join in one click. - **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:** signed in **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `items` | object[] | yes | | | `items[].workspaceId` | string | yes | at least 1 characters | | `items[].name` | string | yes | at least 1 characters | | `items[].memberCount` | integer | yes | at least 0 | | `items[].role` | "member" · "viewer" | yes | | Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)). ### [[POST]] `/v1/workspaces/{ws}/join` Join a workspace whose verified company domain matches your verified address. - **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:** signed in, verified address | Parameter | In | Type | Required | Notes | |---|---|---|---|---| | `ws` | path | string | yes | 1 to 128 characters | **Request body** (`application/json`) An empty object: `{}`. **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `session` | object | yes | | | `session.user` | object | yes | | | `session.workspaceId` | string | yes | at least 1 characters | | `session.workspaceRole` | "owner" · "admin" · "builder" · "member" · "viewer" | yes | | | `session.devLogin` | boolean | 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}/join-domain` The company-domain rule: which domain, whether it is verified, who may join (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 | **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `domain` | string or null | yes | | | `status` | "none" · "pending" · "verified" | yes | | | `record` | object or null | yes | | | `record.type` | "TXT" | yes | | | `record.host` | string | yes | | | `record.value` | string | yes | | | `autoJoin` | boolean | yes | | | `role` | "member" · "viewer" | yes | | | `verifiedAt` | string (date-time) or null | yes | | | `suggestion` | 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)). ### [[PUT]] `/v1/workspaces/{ws}/join-domain` Claim a company domain: returns the DNS record that proves it is yours (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 | |---|---|---|---| | `domain` | string | yes | 3 to 253 characters | **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `domain` | string or null | yes | | | `status` | "none" · "pending" · "verified" | yes | | | `record` | object or null | yes | | | `record.type` | "TXT" | yes | | | `record.host` | string | yes | | | `record.value` | string | yes | | | `autoJoin` | boolean | yes | | | `role` | "member" · "viewer" | yes | | | `verifiedAt` | string (date-time) or null | yes | | | `suggestion` | 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)). ### [[PATCH]] `/v1/workspaces/{ws}/join-domain` Turn auto-join on or off and pick Member or Viewer, once verified (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 | |---|---|---|---| | `autoJoin` | boolean | | | | `role` | "member" · "viewer" | | | **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `domain` | string or null | yes | | | `status` | "none" · "pending" · "verified" | yes | | | `record` | object or null | yes | | | `record.type` | "TXT" | yes | | | `record.host` | string | yes | | | `record.value` | string | yes | | | `autoJoin` | boolean | yes | | | `role` | "member" · "viewer" | yes | | | `verifiedAt` | string (date-time) or null | yes | | | `suggestion` | 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)). ### [[DELETE]] `/v1/workspaces/{ws}/join-domain` Forget the company domain: nobody can join with it any more (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 | **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `ok` | true | yes | | Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)). ### [[POST]] `/v1/workspaces/{ws}/join-domain/verify` Look for the DNS record and, if it is there, verify the domain (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`) An empty object: `{}`. **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `domain` | string or null | yes | | | `status` | "none" · "pending" · "verified" | yes | | | `record` | object or null | yes | | | `record.type` | "TXT" | yes | | | `record.host` | string | yes | | | `record.value` | string | yes | | | `autoJoin` | boolean | yes | | | `role` | "member" · "viewer" | yes | | | `verifiedAt` | string (date-time) or null | yes | | | `suggestion` | 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}/members` Everyone in the workspace with their role, the people with most say first. - **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 (viewers too) | Parameter | In | Type | Required | Notes | |---|---|---|---|---| | `ws` | path | string | yes | 1 to 128 characters | **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `you` | string | yes | at least 1 characters | | `yourRole` | "owner" · "admin" · "builder" · "member" · "viewer" | yes | | | `items` | object[] | yes | | | `items[].user` | object | yes | | | `items[].role` | "owner" · "admin" · "builder" · "member" · "viewer" | yes | | | `items[].joinedAt` | string (date-time) | yes | | | `items[].accessEndsAt` | string (date-time) or null | yes | | | `items[].online` | boolean | yes | | Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)). ### [[PATCH]] `/v1/workspaces/{ws}/members/{userId}` Change someone's role, or the date their access ends (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 | | `userId` | path | string | yes | | **Request body** (`application/json`) | Field | Type | Required | Notes | |---|---|---|---| | `role` | "owner" · "admin" · "builder" · "member" · "viewer" | | | | `accessEndsAt` | string (date-time) or null | | | **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `user` | object | yes | | | `user.kind` | "user" | yes | | | `user.id` | string | yes | at least 1 characters | | `user.name` | string | yes | at least 1 characters | | `user.email` | string | yes | at least 3 characters | | `user.initials` | string | yes | 1 to 3 characters | | `user.color` | "sky" · "pool" · "bubblegum" · "leaf" · "lilac" · "sun" · "tangerine" · "tomato" | yes | | | `role` | "owner" · "admin" · "builder" · "member" · "viewer" | yes | | | `joinedAt` | string (date-time) | yes | | | `accessEndsAt` | string (date-time) or null | yes | | | `online` | boolean | yes | | Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)). ### [[DELETE]] `/v1/workspaces/{ws}/members/{userId}` Remove someone (admins), or leave the workspace yourself (anyone but the last owner). - **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; or yourself (leave) | Parameter | In | Type | Required | Notes | |---|---|---|---|---| | `ws` | path | string | yes | 1 to 128 characters | | `userId` | path | string | yes | | **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `ok` | true | yes | | Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)). ### [[POST]] `/v1/workspaces/{ws}/members/{userId}/transfer-ownership` Hand the workspace to someone else and become an admin (the owner only). - **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:** owner | Parameter | In | Type | Required | Notes | |---|---|---|---|---| | `ws` | path | string | yes | 1 to 128 characters | | `userId` | path | string | yes | | **Request body** (`application/json`) | Field | Type | Required | Notes | |---|---|---|---| | `confirmName` | string | yes | 1 to 120 characters | **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `ok` | true | yes | | Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).