Authentication

API Keys

CampaignStack uses API keys for authentication. Keys are scoped to a workspace and grant specific permissions.

Key format

cs_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
└──┘└──────────────────────────────────┘
prefix        32 hex characters

Keys start with cs_ followed by 32 random hex characters (16 bytes of entropy).

Creating a key

1. Go to Settings > API Keys in your workspace
2. Click Create API Key
3. Name the key and select scopes
4. Copy the key immediately — it’s shown only once

Caution

The plaintext key is displayed only at creation time. CampaignStack stores a SHA-256 hash — the original key cannot be retrieved later.

Using a key

Pass the key as a Bearer token in the Authorization header:

curl -X POST https://mcp.campaignstack.io/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cs_your_api_key_here" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Key lifecycle

• Active — key is valid and can authenticate requests
• Revoked — key is permanently disabled (soft delete via revokedAt timestamp)
• Keys track lastUsedAt for auditing
• Validation results are cached for 60 seconds

Scopes

Each API key is granted a set of scopes that control which tools it can call. Scopes follow the pattern {domain}:{action}.

See the Scopes reference for the full permission matrix.

Verifying access

Call campaignstack_whoami to check your current permissions:

{
  "workspaceId": "abc123",
  "workspaceName": "My Agency",
  "scopes": ["campaigns:read", "campaigns:write", "leads:read"],
  "keyPrefix": "cs_a1b2c3"
}

This tool requires no specific scope — any valid key can call it.

Server-to-server auth

For internal service communication, CampaignStack supports a separate authentication method using the X-Runner-Secret header with additional context headers (x-workspace-id, x-user-id). This grants all scopes and is used by the runner service.