Connect
Developers: API keys
Create, rotate and revoke API keys, choose what each key can do, set its limits, and read the in-app API reference.
Where to find it#
In the sidebar, under Developers, click API. The page has two tabs: Keys, where you manage API keys, and Reference, the Officely API reference.
Only workspace owners and admins see this page. If you can't find it, ask an owner or admin of the workspace. See Team.
API keys connect your own systems to Officely: your store or CRM sending messages through a Catch Hook, Make or Zapier, or an AI assistant using the Officely MCP server.
Create a key#
- 1
Click Create key
On the Keys tab, click Create key.
- 2
Name it
Name it after the system that will use it, for example
Store production. Use one key per system, so you can rotate or revoke it on its own. - 3
Choose what it can do
Under What can this key do?, pick a quick choice or tick the permissions you need (next section). Leave everything unticked for Messaging only.
- 4
Copy the key now
Click Create key. In Copy your new key, click Copy and store the key in your server's secrets. You won't see it again. Click I've saved it to close.
Send the key in the x-officely-token header of every request. New keys start with ofl_live_.
The keys table shows each key's name, the start of the key, when it was created, when it was Last used and who created it.
Choose what a key can do#
Every key can always send messages (/sendMessage) and check its token. Everything else in the Officely API and the MCP server needs a permission. Start with a quick choice:
| Quick choice | What the key can do |
|---|---|
| Messaging only | Send messages and check its token. Right for a store, CRM, Make or Zapier. |
| Read only | Also read chatbots, AI flows, scheduled messages and account status. Changes nothing. |
| Build drafts (MCP) | Read chatbots and AI flows, edit their drafts and run tests in preview. Can't publish. Right for an AI assistant using MCP. |
| Full access | Everything, including publishing, except Read personal data. |
You can also tick single permissions, grouped under Chatbots, AI flows, Conversations and Account. Permissions marked Changes live bots can change what your customers get or spend AI credits; Personal data permissions read your customers' details. A warning appears when you pick a permission that changes live bots: give those only to tools you trust.
Read conversations masks phones, emails, names and card numbers. Read personal data shows them unmasked, and turns on Read conversations with it. Choose it only for systems allowed to process your customers' personal data.
To change a key's access later, click Access under its name, change the permissions and click Save access. The key uses the new access from its next request.
Limit a key#
Limits stop one key from doing too much. Click the limits summary under a key's name to open Limits for that key. Leave a field empty for no limit.
| Limit | What happens when it's hit |
|---|---|
| Monthly AI credit limit | AI work done through this key (API and MCP test runs) stops for the rest of the month. Shown only on accounts that use AI credits. |
| Requests per minute | Extra requests in the same minute get a "too many requests" error. 60 a minute suits most integrations. |
| Chatbots this key can use | All chatbots, or Only these chatbots. Requests for other chatbots are refused. |
| Stops working after | The key stops working at the end of this day (UTC). Leave empty to keep it working until you revoke it. |
Click Save limits. The window also shows the key's requests and credits this month.
When a limit is hit, requests with this key get an error that names the limit. Other keys and your bots are not affected. To fix it, raise the limit, or wait for the next minute or month.
Rotate or revoke a key#
- 1
Rotate
Click Rotate on the key's row, then Rotate key. You get a new key to copy right away. The old one keeps working for 24 hours, so you can update your systems without downtime.
- 2
Revoke
Click Revoke, then Revoke key. Requests that use the key fail right away. This can't be undone.
Rotate a key on a schedule, or right away if it may have leaked. Revoke a key you no longer use.
Legacy token#
Below your keys, the Legacy token (the account token) is the token integrations set up before API keys use: Make, Zapier and anything that sends to a Catch Hook. It is shown in your own workspace only. Click the eye to show it and the copy button to copy it.
Click Rotate legacy token, then Rotate now, to replace it. Everything that sends the current token stops working right away, so update those integrations with the new one. You stay signed in; other browsers and devices need to sign in again.
For anything new, create an API key instead: you can name, limit, rotate and revoke it on its own.
API reference#
The Reference tab is the Officely API reference, with ready-to-copy examples. It covers authentication, checking a token (GET /checkToken), triggering a Catch Hook (POST /sendMessage), the variables you can use in messages, and errors.
For a step-by-step guide to sending messages, see Catch Hook & API.
If something goes wrong#
- No Developers group in the sidebar: your role can't manage API keys. Ask an owner or admin.
- "We couldn't load your keys.": click Try again. If it keeps happening, email info@officely.ai.
- Requests fail with 401: the key is missing, wrong, revoked or expired. Check the
x-officely-tokenheader, or create a new key. - A key stopped working after a rotation: the old key works for 24 hours only. Update your system with the new key.