Skip to main content
An organisation is divided into workspaces: offices, regions or teams, each with its own packages, templates, contacts and members. Every organisation has a default workspace. An API key is issued for one or more workspaces, chosen when it is created at Settings > API keys. The first one chosen is the key’s default: a call on an ordinary key that names no workspace acts there. The list cannot be changed afterwards; to reach a workspace that is not on the key, issue another key.

Listing workspaces

GET /api/v1/workspaces returns the workspaces the key covers, and confirms in active which workspace the call acted in. On a key that acts for members, the list is narrowed to the workspaces the named member belongs to, and the call must send X-Act-As and X-Workspace-Id like any other.
isDefault marks the organisation’s default workspace, not the key’s. The key’s default is the one active reports when you send no header.

The X-Workspace-Id header

The header is optional on an ordinary key. Send it to choose which of the key’s workspaces a call acts in. Packages and templates you list, create or act on are scoped to that workspace.
Rules:
  • Omit the header to act in the key’s default workspace.
  • A key that acts for members must always send it. It has no default workspace, and a call without the header returns 400. See Keys that act for members.
  • Name any workspace on the key to act there for that call. Each call is independent, so one key can work across its workspaces request by request.
  • Any other id (unknown, or a workspace in the organisation that is not on the key) returns 401. The call never falls back to the default and is never widened to the whole organisation.
  • GET /api/v1/workspaces reports the workspace actually used in active, so you can confirm a header was honoured.
Webhook endpoints are workspace-scoped too. An endpoint belongs to the workspace the registering call acted in and receives events only for that workspace’s packages, and GET /api/v1/webhooks lists the endpoints of the workspace the call acts in. To receive events from another workspace, register an endpoint with X-Workspace-Id set to it. See Webhooks.