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.
11 routes. Every path starts at https://cloud-api.qaldy.com. Sign-in, tokens, errors and limits are on the overview.
Routes#
| Method | Path | What it does |
|---|---|---|
| GET | /v1/me/join-suggestions | Workspaces your verified company address can join in one click |
| POST | /v1/workspaces/{ws}/join | Join a workspace whose verified company domain matches your verified address |
| 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 | Claim a company domain: returns the DNS record that proves it is yours (admins) |
| 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 | Forget the company domain: nobody can join with it any more (admins) |
| 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 | Everyone in the workspace with their role, the people with most say first |
| PATCH | /v1/workspaces/{ws}/members/{userId} | Change someone's role, or the date their access ends (admins) |
| 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 | 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_onlyfor 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).
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_onlyfor 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).
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_onlyfor 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).
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_onlyfor 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).
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_onlyfor 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).
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_onlyfor 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).
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_onlyfor 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).
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_onlyfor 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).
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_onlyfor 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).
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_onlyfor 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).
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_onlyfor 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).