Acting on behalf of a workspace (delegation)

This guide explains the reserved workspaceId argument, accepted by every verb tool (read, create, update, delete, act). You only need it when you want to operate as one of your workspaces (sub-organizations) instead of your own organization. For all normal calls, leave workspaceId out of arguments.

workspaceId and clientspaceId are mutually exclusive — set at most one per call. Setting both is rejected with delegation_conflict before the operation runs.

What a workspace is

A workspace is a sub-organization under your account with its own isolated data (campaigns, prospects, lists, senders) and its own API key. Workspace API keys are resolved server-side; the apiKey field is redacted from every workspace/* response, so you never see, store, or pass it. You reference a workspace by its integer workspaceId, and the server supplies the right key.

Workspaces are available on every plan — no upgrade required. For a whitelabel sub-organization (clientspace) with branding capabilities, see clientspace-delegation.

Delegation is key-based, not login-based — no operation hands a client their own sign-in to a workspace, and none converts a workspace into a clientspace (or back): that choice is made at creation.

The flow

1. Discover your workspaces

read(name: "workspace/get", intent: { ... })

Each item has its workspaceId, title, etc. Pick the workspaceId you want to act on behalf of. (You can also fetch a single one with workspace/get_by_id.)

2. Run any operation on behalf of that workspace

Add workspaceId to the operation's arguments, alongside its normal arguments:

read(
  name: "campaign/get",
  arguments: { "pageQuery.limit": 10, workspaceId: 44298 },
  intent: { ... }
)

The server looks up workspace 44298, authenticates the request with that workspace's API key, and returns its data. The same workspaceId argument works on any operation — it is accepted everywhere, even though it appears in no operation's Arguments table.

3. Go back to acting as yourself

Omit workspaceId. There is no persistent switch — delegation is per call.

Notes & errors

• workspaceId is a single positive integer inside arguments. It scopes the call and is never forwarded to the operation itself.
• It is mutually exclusive with clientspaceId; setting both → delegation_conflict.
• A non-integer or non-positive value → delegation_invalid, before the operation runs.
• A workspaceId that does not exist or is not under your organization → workspace_not_found, before the operation runs.
• A workspace with no usable key → workspace_key_unavailable.
• You never handle the workspace's API key; the server resolves, caches, and redacts it.