Workspaces & multi-brand setup for agencies and holding cos

How to set up CitationBench when you're running organic visibility for more than one brand. Most of this is choices, not steps — but they all happen up front.

For the deep concept, see Concept · Workspaces. This page is the practical setup guide.

The two starting points

Pick the one that matches you.

Solo operator / in-house team — one workspace

• Sign up
• Get a workspace-scoped sk_live_*** key
• All API calls automatically scoped to your workspace; no X-Workspace-Id header needed
• Skip the rest of this page; go to Quickstart — REST

Agency / holding co — many workspaces, one master account

• Sign up for an agency account
• Get an **agency master sk*live*\***** key + a series of workspace-scoped keys
• Each client brand = one workspace
• Pass X-Workspace-Id: ws_*** on every call (or use workspaces.bulk_action for cross-workspace ops)

The rest of this page is for the agency / multi-brand case.

Step 1 — Create the agency account

Sign up at https://app.citationbench.com/agency-signup (or convert an existing single-workspace account via Settings → Convert to agency).

You'll get:

• An agency master API key (sk_live_agency_***)
• A "main" workspace for your own marketing
• The ability to create sub-workspaces under your agency

Step 2 — Create a workspace per client

curl -X POST https://api.citationbench.com/v1/workspaces \
  -H "Authorization: Bearer sk_live_agency_***" \
  -d '{
    "name":          "Acme PM",
    "primaryDomain": "acme.com",
    "tags":          ["industry:saas", "tier:premium"],
    "settings": {
      "primaryLocation":  "us",
      "primaryLanguage":  "en",
      "approvalPolicy": {
        "publish":         "require_approval",
        "outreach_send":   "require_approval",
        "indexing_submit": "auto"
      },
      "creditPool":       "agency"
    }
  }'

Repeat per client. Or do it in bulk:

for DOMAIN in acme.com beta.io gamma.shop; do
  curl -X POST .../v1/workspaces -d "{
    \"name\":          \"$DOMAIN\",
    \"primaryDomain\": \"$DOMAIN\"
  }"
done

You can also create + bootstrap in one call:

curl -X POST .../v1/agent/invoke -d '{
  "skill": "bootstrap_brand",
  "input": { "domain": "newclient.com", "workspace": "auto" }
}'

workspace: "auto" creates a fresh workspace named after the domain and fills it with ICP, keywords, competitors, and a content plan in ~20 minutes.

Step 3 — Connect integrations per workspace

Each workspace has its own integrations. The most common:

Setup once per workspace; durable until revoked.

Step 4 — Decide on credit pooling

Two patterns:

Per-workspace credits (default for new sub-workspaces)

• Each client has their own credit allowance + own billing transparency
• Useful when clients pay-per-credit or have spend caps

Agency-pooled credits (settings.creditPool: "agency")

• One pool, drawn from by any workspace
• Useful when the agency manages spend and bills clients monthly

You can mix — pool some workspaces, isolate others.

Step 5 — Decide on approval policy

Per workspace (or inherited from agency-level default):

curl -X PATCH .../v1/workspaces/ws_acme -d '{
  "settings": {
    "approvalPolicy": {
      "publish":         "require_approval",
      "outreach_send":   "require_approval",
      "indexing_submit": "auto"
    }
  }
}'

The recommended default for agency workspaces: approve outside-world actions (publishing, outreach), auto-approve internal-state actions (indexing requests, internal labels).

Wire approval webhooks into your client portal or Slack to surface previews to clients:

curl -X POST .../v1/webhooks -d '{
  "url":    "https://hooks.our-portal.com/approvals",
  "events": ["agent.invocation.awaiting_approval"]
}'

Step 6 — Cross-workspace operations

The agency-defining endpoint:

curl -X POST .../v1/workspaces/bulk-action \
  -H "Authorization: Bearer sk_live_agency_***" \
  -d '{
    "action":     "agent.invoke",
    "workspaces": "all",
    "config": {
      "skill": "rank_monitor",
      "input": { "alertOn": { "drop": 5 } }
    }
  }'

One call. One scheduled rank check across every client. One alert webhook. One client report.

You can fan out any tool — research, production, indexing, link-building — with per-workspace variable substitution ({{ workspace.* }}).

How to think about the agency workflow

Agency master key
  │
  ├── ws_client-alpha      ← own integrations, own approvals, own credit pool
  ├── ws_client-beta       ← same
  ├── ws_client-gamma      ← same
  └── ws_agency-internal   ← your own marketing
       │
       └── cross-workspace bulk ops via /v1/workspaces/bulk-action

A typical week:

• Monday: bulk rank check + portfolio report
• Throughout week: per-workspace content_factory runs queue blog posts; agent surfaces drafts at WAITING_APPROVAL
• Daily: link-building inbound_negotiator runs in each workspace; pending review items roll up to the agency inbox
• Weekly: link_hunter skill runs SERP + competitor outreach in each workspace; drafts queue for approval
• Continuously: citation_hunter tracks AI search citations daily; reclaim drafts queue

Common patterns

One agency key, many sub-keys for staff

# Create per-staff workspace-scoped keys
curl -X POST .../v1/auth/keys -d '{ "name": "marina", "scope": "WORKSPACE", "workspaceId": "ws_acme" }'

Marina can only act on ws_acme. The agency master key can still oversee everything.

White-label (roadmap)

workspace.whiteLabel settings let you customize brand on per-client dashboards, reports, and outreach footers. Roadmap; current beta available on request.

Auditing per workspace

curl -G .../v1/workspaces --data-urlencode "include=usage,health,lastActiveAt"

Per-workspace usage + integration health, in one call. Pipe to your agency dashboard.

Next

• Quickstart — REST — your first call
• Quickstart — MCP — via Claude Code / Cursor / Claude Desktop
• Authentication — keys, scopes, demo mode
• Concept · Workspaces
• API · Workspaces
• Playbook: Weekly rank checks across all clients