Skip to main content

​
Workspace group

A workspace group allows you to control multiple workspaces (sub workspaces) from within a single admin workspace. Read on 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 API endpoints. The API key must have the same scopes as it would when the endpoints are called normally.

​
Call API endpoints “as” a specific sub workspace

You need to add an extra header to your requests called x-as-workspace and set its value to the workspace id of the sub workspace. That is the only difference between a regular API call and a call on behalf of a sub workspace. If you do not provide the x-as-workspace header, requests will go through as usual.

​
Limitations

There are a few limitations regarding this feature:
  1. For privacy and security reasons, a workspace cannot be both an admin workspace and a sub workspace at the same time.
    • If you own an admin workspace, it cannot be a sub workspace.
    • If your workspace is managed by an admin workspace, it cannot be an admin workspace.
  2. Only workspace owners and admins can invite workspaces to join their workspace group.
  3. Only workspace owners and admins can remove sub workspaces from the admin workspace.
  4. Only workspace owners can leave a workspace group.

​
Adding sub workspaces

There are two ways to add sub workspaces — from the app and using the API. For both methods, you will need the ID of the workspace you want to invite. Important: both methods send an invitation to the workspace owner. The workspace becomes a sub workspace only after the invitation is accepted.

​
Adding sub workspaces from the app

  1. Go to the Settings > Account page.
  2. Go to the Workspace Group tab.
  3. Click the Add sub workspace button.
  4. Paste the workspace ID into the text field.
  5. 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

  1. Use the POST /workspace-group-members endpoint.
  2. Set the sub_workspace_id field to the workspace ID you want to invite.
  3. 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

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

​
Removing sub workspaces using the API

  1. Use the GET /workspace-group-members endpoint to fetch a list of sub workspaces for your current workspace.
  2. Identify the item where sub_workspace_id matches the workspace ID you want to remove.
  3. Send a request to DELETE /workspace-group-members/:id, replacing :id with the id field of the workspace group member from the previous step. Note: the id is the workspace group member ID, not the workspace ID.
  4. 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

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

​
Leaving a workspace group through the API

  1. Call the GET /workspace-group-members/admin endpoint.
  2. Get the workspace_group_member_id field (this is the id field of the workspace_group_member).
  3. Send a request to DELETE /workspace-group-members/:id, replacing :id with the workspace_group_member_id from the previous request.
  4. Your workspace will immediately leave the workspace group.