Skip to main content

​
Workspace API keys

Public REST requests use a SendPilot workspace API key:
Authorization: Bearer sp_live_... or Bearer sp_test_... is also accepted. Use one authentication header; X-API-Key takes precedence if both are supplied. The key determines the workspace. Adding a workspace header or changing an ID does not grant access to another workspace. Use a separate key for each workspace. Start with Get workspace and key to check the effective scopes, expiry, rate limits, and subscription state.

​
Create or reuse a key

  1. Select the intended workspace in SendPilot.
  2. Open Integrations → API Keys, or select an API-key client in Integrations → MCP.
  3. Choose Create API Key and save the full value when it is shown.
  4. In MCP setup, Use Key for Setup supplies a newly created key to the selected client’s configuration. Use Saved Key accepts a full key you previously saved.
The REST API and API-key MCP clients use the same keys. Masked values cannot be recovered. Revoking a key affects every REST integration and MCP client using it. Keep raw keys in your local secret store or environment, not URLs, chat messages, or version control.

​
Effective permissions

Each operation declares its required scopes in the OpenAPI x-sp-scopes extension. The current REST API uses: Write scopes imply the corresponding read scopes; inbox:send implies inbox:read, and lead_sourcing:run implies leads:read. Registry scopes for other capabilities do not imply that a public endpoint or MCP tool exists. The endpoint reference and MCP tool catalog define the available operations. Keys stored without explicit scopes retain the legacy full-scope policy, still capped by their creator’s current membership and permissions. An empty scope list is not a way to create a no-access key. /v1/me reports apiKey.scopes, apiKey.fullAccess, and missingScopes. Scopes do not override workspace roles. Campaign resume additionally requires inbox:send, as does importing into a running campaign. For credentials with a recorded creator, resume also requires ALLOW_CREATE_CAMPAIGN; database searches require ALLOW_LEAD_FINDER; extraction requires ALLOW_LEAD_EXTRACTION. Removing the creator from the workspace or reducing their rights can remove access immediately. Historical keys without a recorded creator retain their legacy scope policy.

​
MCP OAuth is a separate connection method

Claude and ChatGPT web connectors use a dashboard-created OAuth connection URL. Clerk handles sign-in, consent, token exchange, and refresh. Those OAuth tokens authenticate to that exact MCP resource; they are not API keys for direct /v1 requests. New dashboard OAuth connections preselect Read and Write. Users can select Read Only before creating the connection. This UI default does not change existing grants or the API-key scope policy. See client setup.

​
Authentication errors

See limits, errors, and retries for billing refusals, rate limits, and idempotent writes.