API tokens and developer keys
There are two kinds of credential for code that talks to your workspace.
- Who can use this
- Developer, Account owner, Manager
There are two kinds of credential for code that talks to your workspace.
There are two kinds of credential for code that talks to your workspace. Developer keys are made in the developer portal and are the keys for the REST API. API tokens are personal access tokens made in Settings → Integration → API Tokens. This page explains both, how to create them, and how to revoke or replace them.
The portal opens signed in.
New keys can only read until you tick more.
If you pick never, tick I understand this key never expires. Revoke it when it is no longer needed.
It is shown once only.
Confirm with your two-factor code if asked.
You will not see it again.
Neither screen has a rotate button. To rotate:
To change a developer key's IP allowlist, do the same: make a new key with the new list, switch over, revoke the old key.
| Scope | Lets the key |
|---|---|
mcp:read | Read your data (always included) |
crm:write | Create and edit contacts, tags, contact groups and custom fields |
messaging:write | Send WhatsApp messages; manage templates and quick messages |
inbox:write | Manage conversations: notes, assign, close, tags, reminders |
bots:write | Control the chatbot in conversations: turn it on or off, choose, switch or restart the bot (a restart messages the customer) |
webhooks:write | Manage webhook endpoints |
hours:write | Create and edit business hours, holidays and special opening days |
broadcasts:send | Send WhatsApp broadcasts: live keys with an IP allowlist only, and it needs your two-factor code (marked Sensitive) |
A call without the right scope gets 403 insufficient_scope. The portal's Keys and permissions guide has the current list.
broadcasts:send) needs a live key, an IP allowlist and your two-factor code. The workspace must also allow broadcasts from API keys.0.0.0.0/0.401 unauthenticated)./v1, the developer portal's API) accepts developer keys only. An API token from Settings → Integration → API Tokens is refused there with 401. API tokens work with the MCP server and the older panel API, for example the template request on the API Help page.The Copilot cannot create or revoke keys or tokens. Do this in the panel or the portal.
| What you see | Why | What to do |
|---|---|---|
| "Token name is required" | The name field is empty | Enter a Token Name |
| "Failed to generate API token" | The server refused or the connection dropped | Try again; check you still have Manage Settings |
| "Only staff who can manage workspace settings can create or revoke developer keys. Ask a workspace manager." | You do not have Manage Settings | Ask a manager |
| "Set up two-step sign-in first" | You ticked Sends broadcasts without 2FA on your profile | Turn on two-step sign-in in your profile's security settings |
| "Add a valid IP allowlist to create a key that can send broadcasts." | Broadcast keys need an allowlist | Add your servers' outbound addresses |
401 unauthenticated | Key revoked, expired, mistyped, or called from outside its allowlist | Check the key's status and your server's outbound IP |
403 insufficient_scope | The key lacks the permission for this call | Make a new key with the scope |