# Authentication and permissions

> API keys, the 20 scopes and what each one unlocks, key rotation, rate limits per plan and workspace isolation for the WhatSetter API.

Source: https://docs.whatsetter.com/developers/authentication/

Every request to the API and every MCP session is authenticated with an API key. This page explains what a key is, what it can do, and the limits that apply to it.

## API keys

- Format: `ws_live_` followed by 40 hexadecimal characters.
- A key belongs to the **workspace**, not to a person. It is created in **Settings**, then **API & MCP**, by an owner or an admin.
- It is shown **once**, right after creation. WhatSetter only stores a fingerprint, so nobody can read it back later.
- You can revoke it at any time with **Revoke**, then **Revoke for good**. The dashboard confirms: **Key revoked. Effective within a minute.** Revoking cuts the REST API and the [MCP server](/developers/mcp/) at the same time.

## Send the key

Pass the key as a Bearer token. The `X-Api-Key` header is accepted too.

```bash
curl https://app.whatsetter.com/api/v1/me \
  -H "Authorization: Bearer ws_live_…"
```

Without a key you get `401 missing_api_key`. With an unknown or revoked key you get `401 invalid_api_key`.

## Scopes

When you create a key you choose its **Permissions**: **Full access** (every scope, including sending messages and changing prompts) or **Custom** (pick exactly what this key can do). A key without the right scope gets `403 insufficient_scope`, and the message names the missing scope.

| Scope | What it unlocks | Endpoints |
|---|---|---|
| `leads:read` | Read leads and their notes | `GET /leads`, `GET /leads/{id}`, `GET /leads/{id}/notes` |
| `leads:write` | Update status, tags, owner, next action and deal outcome; hand a conversation to a human and give it back; add notes | `PATCH /leads/{id}`, `POST /leads/{id}/handoff`, `POST /leads/{id}/resume`, `POST /leads/{id}/notes` |
| `conversations:read` | Inbox and full message history | `GET /conversations`, `GET /conversations/{leadId}/messages` |
| `lists:read` | List your contact lists | `GET /lists` |
| `lists:write` | Create lists and import contacts | `POST /lists`, `POST /lists/{id}/leads` |
| `campaigns:read` | List campaigns | `GET /campaigns` |
| `campaigns:write` | Pause and resume campaigns | `POST /campaigns/{id}/pause`, `POST /campaigns/{id}/resume` |
| `messages:send` | Send a message to a lead already in conversation, on WhatsApp, Instagram or Messenger; add an opt-in lead to a campaign (this sends their first message) | `POST /messages`, `POST /campaigns/{id}/leads` |
| `bookings:read` | Meetings booked by the agent | `GET /bookings` |
| `groups:read` | Tracked WhatsApp groups: details, members, messages, join and leave events | `GET /groups`, `GET /groups/{id}`, `GET /groups/{id}/members`, `GET /groups/{id}/messages`, `GET /groups/{id}/events` |
| `webhooks:manage` | Create, list, test and delete webhook subscriptions | `GET /webhooks`, `POST /webhooks`, `DELETE /webhooks/{id}`, `POST /webhooks/{id}/test` |
| `blocklist:manage` | Read, add and remove blocked numbers and dial prefixes | `GET /blocked-contacts`, `POST /blocked-contacts`, `DELETE /blocked-contacts/{id}` |
| `team:read` | List the members of the workspace (id, name, role), to assign leads | `GET /team/members` |
| `links:read` | Read tracked links and their click stats | `GET /links`, `GET /links/{id}` |
| `prompts:read` | Read the prompts an agent runs on and their versions | `GET /campaigns/{id}/prompts`, `GET /campaigns/{id}/prompts/{type}`, `GET /campaigns/{id}/prompts/{type}/versions`, `GET /campaigns/{id}/prompts/{type}/versions/{versionId}` |
| `prompts:write` | Change a prompt or restore a version. The change is live at once | `PUT /campaigns/{id}/prompts/{type}`, `POST /campaigns/{id}/prompts/{type}/versions/{versionId}/restore` |
| `knowledge:read` | Read knowledge bases and their answers, and search them as the agent does | `GET /knowledge-bases`, `GET /knowledge-bases/{id}`, `GET /knowledge-bases/{id}/search`, `GET /knowledge-bases/{id}/answers` |
| `knowledge:write` | Add, correct and remove answers | `POST /knowledge-bases/{id}/answers`, `PATCH /knowledge-bases/{id}/answers/{answerId}`, `DELETE /knowledge-bases/{id}/answers/{answerId}` |
| `instagram:read` | Read the Instagram accounts, the planned posts, the posts' numbers and best times, the automations and their numbers | `GET /instagram/accounts`, `GET /instagram/posts`, `GET /instagram/posts/{id}`, `GET /instagram/insights/posts`, `GET /instagram/insights/best-times`, `GET /instagram/automations`, `GET /instagram/stats` |
| `instagram:write` | Plan, change and cancel posts (they are published publicly); create, change, switch on and delete automations (an active one writes to real people) | `POST /instagram/posts`, `PATCH /instagram/posts/{id}`, `DELETE /instagram/posts/{id}`, `POST /instagram/automations`, `PATCH /instagram/automations/{id}`, `DELETE /instagram/automations/{id}` |

`GET /me` needs no scope: any valid key can call it.

> **Six scopes are new**
`prompts:read`, `prompts:write`, `knowledge:read` and `knowledge:write` were added with the prompts and knowledge base endpoints. A key created before that does not carry them, even a **Full access** one: create a new key if you need those endpoints. The same holds for `blocklist:manage`, `team:read` and `links:read`, added earlier. See the guides on [agent prompts](/developers/guides/prompts/) and [knowledge bases](/developers/guides/knowledge/).

> **Instagram needs a recent key**
`instagram:read` and `instagram:write` came with the Instagram endpoints. A **Full access** key is the list of scopes that existed the day it was made, so a key made before these endpoints were released does not carry them and the Instagram routes answer `403 insufficient_scope`. Create a new key. Instagram and Messenger private messages need no Instagram scope: they are read with `conversations:read` and answered with `messages:send`, like WhatsApp. See the [Instagram guide](/developers/guides/instagram/).

## Least privilege

- One key **per integration** (CRM, Zapier, a script, an AI assistant). Revoking one does not break the others, and the dashboard shows when each was last used.
- A dashboard or a report needs read scopes only. Grant `messages:send` only to the integration that really sends messages.
- Grant `prompts:write` only to an integration or an assistant that should change what your agents say. With `prompts:read` alone it can explain a reply without being able to change anything.
- Keys given to an AI assistant through the [MCP server](/developers/mcp/) deserve the same care: the assistant can only do what the key allows.

## Rotate a key

1. In **Settings**, then **API & MCP**, click **Create a key** with the same scopes as the old one.
2. Put the new key in your integration and check it with `GET /me`.
3. Click **Revoke** on the old key, then **Revoke for good**. It stops working within a minute.

Rotate right away if you suspect a leak: a key that was pasted in a chat, a ticket or a public repository.

## One key for the API and the MCP server

The [MCP server](/developers/mcp/) does not have its own accounts. Every tool call is a call to the REST API with your key, so the scopes, the rate limits and the anti-ban rules below apply exactly the same way. Revoke the key and the assistant loses access too.

## Rate limits

Requests are counted **per workspace, per minute**, all keys combined. The limit depends on your plan:

| Plan | Requests per minute |
|---|---|
| Social | 30. Lists, groups, links and webhooks need a WhatsApp plan: `403 not_in_plan` |
| Free | 60 |
| Starter | 120 |
| Business | 300 |
| Scale | 1000 |

Every response carries three headers:

| Header | Meaning |
|---|---|
| `X-RateLimit-Limit` | Your plan's limit for the current window. |
| `X-RateLimit-Remaining` | Requests left in the window. |
| `X-RateLimit-Reset` | When the window resets, ISO 8601. |

Past the limit you get `429 rate_limited` with a `Retry-After` header in seconds. Wait that long, then retry.

Message sends have a separate **daily quota per WhatsApp number**, reported in the `X-Quota-*` headers. See [Errors, limits and idempotency](/developers/errors/).

## Workspace isolation

A key only sees the workspace it belongs to. If you request an id that exists but belongs to another workspace, the API answers `404 not_found`, the same as for an id that does not exist. It never answers `403`, so a foreign id cannot be told apart from an unknown one.

## Related

- [Quickstart](/developers/quickstart/)
- [Errors, limits and idempotency](/developers/errors/)
- [MCP server](/developers/mcp/)
- [Team and roles in the dashboard](/dashboard/team/)
