What a key is
A key is what a system shows each time it calls the API, so that your workspace knows it is allowed. Make one key for each system: if one is lost, you delete it without stopping the others.
API keys lists your keys: each one’s Name, its value hidden but for its first characters, and its Access, Full access or Limited. Total beside the heading says how many there are.
Add a key
On API keys, press Add API key.
The window Add a new API key opens.
Give the key a Name, for example the system that will use it.
Under Access, keep Full access, or choose Limit what this key can do.
See What a key may do below.
Press OK.
The window Your new API key shows the key, and the API’s Base address, each with Copy.
Copy the key, put it in your system’s secret settings, and press I’ve stored it.
It is not shown again. If it is lost, give the key a new value.
What a key may do
| On the screen | What it does |
|---|---|
| Full access | Everything the API does, now and as it grows. Launching, publishing and switching on still wait for an admin. |
| Limit what this key can do | Only what you tick. The key keeps that for good, and never gains anything added to the API later. |
A limited key’s list is grouped by what it acts on: Inbox, Audience, Messaging, Automation, Sales, Workspace and Developer. For each thing, such as Contacts or Templates, you tick what the key may do with it, for example Read or Write. Select all ticks a whole group. Each line says what it allows.
- What is marked Needs admin approval is only ever asked for: an admin approves each request first.
- Reading messages is marked Personal data: it is reading your customers’ own words. Give it only to a system you trust with their conversations.
- What your plan does not include is greyed, and says so. Bookings need the CRM: they say Needs the CRM when your workspace does not have it.
A key never changes consent, an opt-out or a phone number.
Rename, renew or delete a key
The pencil beside a key’s name renames it. The menu at the end of its row has the rest:
| On the screen | What it does |
|---|---|
| New value | Gives the key a new value, shown once. The old one stops working at once: every system using it needs the new one. |
| Delete | The key stops working at once, for good. Webhook endpoints made through it are switched off. |
Give a key a new value, or delete it, as soon as you think somebody else may have it.
Good to know
- A workspace has 20 keys at most.
- A key is kept in a form that cannot be read back, which is why it is shown only once.
- How a system uses its key, and how many calls it may make, is in the developer guide.