Workspace Group

A workspace group allows you to control multiple workspaces (sub workspaces) from within a single (admin) workspace.

Please keep reading for more details about how this feature works.

Using a single API key to manage sub workspaces

You can use a single API key to manage any of your sub workspaces. It works with all the API endpoints. You will need the API key to have the same scopes as it requires when the endpoints are called as usual.

Call API endpoints "as" a specific sub workspace

You need to add an extra header to your requests called x-as-workspace - and set it's value to the workspace id of the sub workspace.
That's all you need - it's just one single difference between a regular API call and a call on behalf of a sub workspace. If you don't provide the x-as-workspace header then the requests will go through as usual.

Limitations

There are a few limitations regarding this feature.

For privacy and security reasons, a workspace can NOT be at the same time an admin workspace and a sub workspace.
a. If you own an admin workspace then it can't be a sub workspace.
b. If your workspace is managed by an admin workspace then it can't be an admin workspace.
Only workspace owners and admins can invite workspaces to join their workspace group.
Only workspace owners and admins can remove sub workspaces from the admin workspace.
Only workspace owners can leave a workspace group.

Adding sub workspaces

There are two ways you can add sub workspaces - from the app, and using the API. For both of these methods, you will have to know the id of the workspace you want to invite.
Important: both of these methods will send an invitation to the workspace owner and the workspace will become a sub workspace only after the invitation is accepted.

Adding sub workspaces from the app

Go to the Settings > Account page
Go to the "Workspace Group" tab
Click the "Add sub workspace" button
Past the workspace id into the text field
Press the "Add sub workspace" button to send the invitation Once the invitation is accepted, the workspace will become a sub workspace.

Adding sub workspaces using the API

Use the POST /workspace-group-members endpoint.
Set the sub_workspace_id field to the workspace id you want to invite.
Send the request. Once the invitation is accepted, the workspace will become a sub workspace.

Removing sub workspaces

You can remove sub workspaces from the app or through the API.

Removing sub workspaces from the app

Go to the Settings > Account page.
Go to the "Workspace Group" tab.
Find the sub workspace under the "Sub workspaces" section.
Click the "Remove" button.
The workspace will be removed immediately.

Removing sub workspaces using the API

Use the GET /workspace-group-members endpoint to fetch a list of sub workspaces for your current workspace.
Identify the item where the sub_workspace_id matches the workspace id you want to remove.
Send a request to the DELETE /workspace-grou-members/:id endpoint and replace the id in the URL with the id field of the workspace group member id from the previous step. Note: the id is the id field of the workspace group member - it's not the workspace id.
The workspace will be removed immediately.

Leaving a workspace group

As a sub workspace, you can always leave the workspace group. You can do it either through the app or through the API.
Remember: only workspace owners can leave workspace groups

Leaving a workspace group through the app

Go to the Settings > Account page.
Go to the "Workspace Group" tab.
Press the "Leave workspace group" button under the "Admin workspace" section.
Your workspace will immediately leave the workspace group.

Leaving a workspace group through the API

Call the GET /workspace-group-members/admin endpoint
Get the workspace_group_member_id field (this is the id field of the workspace_group_member)
Send a request to the DELETE /workspace-grou-members/:id endpoint and replace the id in the URL with the workspace_group_member_id field from the previous request.
Your workspace will immediately leave the workspace group.