> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendler.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and permissions

> Workspace API keys, effective scopes, membership, and the difference between REST and MCP OAuth.

## Workspace API keys

Public REST requests use a SendPilot workspace API key:

```bash theme={null}
curl https://api.sendpilot.ai/v1/me \
  -H "X-API-Key: $SENDPILOT_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](https://docs.sendler.ai/api-reference/endpoint/get-me.md) 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:

| Scope | Current operations |
| - | - |
| `workspace:read` | Inspect the calling workspace and key |
| `campaigns:read` | List and inspect campaigns |
| `campaigns:write` | Pause or resume campaigns |
| `leads:read` | Read leads and sourcing job status/results, including contact data |
| `leads:write` | Import leads and change lead outcomes |
| `inbox:read` | Read conversations and messages |
| `inbox:send` | Send LinkedIn messages and connection requests |
| `senders:read` | List senders and daily quotas |
| `lead_sourcing:run` | Start credit-consuming lead searches and extractions |
| `credits:read` | Read the credit balance |

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](https://docs.sendler.ai/api-reference/introduction.md) and [MCP tool catalog](https://docs.sendler.ai/ai/mcp-tools.md) 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](https://docs.sendler.ai/ai/mcp-clients.md#oauth-connections).

## Authentication errors

| Status / code | Meaning |
| - | - |
| 401 `MISSING_API_KEY` | No accepted key was provided |
| 401 `INVALID_API_KEY` | Key is unknown or invalid |
| 401 `INACTIVE_API_KEY` | Key was revoked or deactivated |
| 401 `EXPIRED_API_KEY` | Key has expired |
| 401 `API_KEY_CREATOR_REMOVED` | The key's creator no longer has workspace access |
| 403 `INSUFFICIENT_SCOPE` | Effective scopes do not cover the operation |
| 403 `INSUFFICIENT_WORKSPACE_PERMISSION` | Creator lacks the operation-specific workspace permission |

See [limits, errors, and retries](https://docs.sendler.ai/api-reference/behavior.md) for billing refusals, rate limits, and idempotent writes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.