API keys and permissions
How API keys work, which permissions and accounts to give them, and how to replace or revoke one safely.
For developers
On this page
Every Agent API request carries an API key. The key decides where the request may act and what it may do. Organization owners and admins manage keys at Settings → API & Webhooks → API keys.
How a key is sent
Put the key in the Authorization header as a bearer token:
curl -s https://app.luminobot.com/api/v1/me/ -H "Authorization: Bearer bb_studio_…"
- Keys start with
bb_studio_. Luminobot stores only a fingerprint of the key, so nobody can read it back later — not even us. That is why it is shown only once. - Requests must use
https://. A key sent over plainhttp://is refused. - Never put the key in a URL or a query string.
What a key can reach
Each key has four limits, set when you create it:
| Limit | What it means |
|---|---|
| Workspace | A key works in exactly one workspace. Create one key per workspace you want to automate. |
| Connected accounts | The key may only use the social accounts you ticked. Anything about other accounts answers 403 or 404. |
| Inbox actions on these accounts | Reply to direct messages, reply to comments, private-reply to comments, assign conversations, change status, add notes. Untick what the key must not do. |
| Permissions | What the key may do in the workspace (below). |
On top of that, a key is never stronger than the person who created it. Every request checks that person's current role: if they lose a permission, the key loses it too, and if they leave the workspace, the key stops working. When someone leaves your team, check the keys they created.
Choosing permissions
Give each key only what its job needs. The most used permissions:
| Permission | Lets the key… |
|---|---|
create_posts |
Create and edit draft posts, use the publishing tools and AI captions. |
publish_directly |
Schedule posts without approval. Without it, a key can only save drafts. |
delete_posts |
Delete any post. Without it, a key can still delete unpublished posts its creator wrote. |
approve_posts |
Approve or reject posts and workflow steps. |
upload_media |
Upload images and videos to the media library. |
view_analytics |
Read analytics, AI insights, competitors, link clicks and ad results. |
use_inbox |
Read conversations, saved replies, macros, CSAT and SLA status. |
reply_from_inbox |
Reply, assign, snooze, change status and priority, use AI reply help. |
use_contacts |
Read contacts, segments and lead form answers. |
manage_contacts |
Change consent, export or erase a contact's data. |
use_workflows |
Read workflows and their runs. |
manage_workflows |
Publish and restore workflow versions. |
manage_workspace_settings |
Manage webhooks and the brand voice. |
The API reference shows which permission each endpoint checks. Call GET /api/v1/me/ at any time to see the permissions a key has right now.
Replacing a key
Keys don't need to be changed on a schedule, but replace one straight away if it may have leaked, and when the person who created it leaves.
- Create a new key with the same workspace, accounts and permissions.
- Put the new key into your tool and check that it works.
- Revoke the old key.
Setting an Expires at date when you create a key is a good habit for keys used in short projects.
Revoking a key
On the API keys tab, find the key and click Revoke, then confirm. It stops working at once: the next request gets 401 Unauthorized. Webhooks the key created are turned off too. Revoking can't be undone. Revoked keys are hidden; the Show … revoked link above the list brings them back into view.
Keys versus AI agent tokens
API keys are for your own software. To connect an AI assistant such as Claude or ChatGPT, use Settings → AI agents (MCP) instead (see Connect your AI assistant). Agent tokens (lb_pat_…) and sign-in tokens work only for AI assistants (MCP), not for the REST API. API keys work for both.
What not to do
- Don't put a key in a website, a mobile app or any code that runs on someone else's device. Anyone could copy it from there.
- Don't commit keys to Git or paste them in chat, email or tickets. Use your tool's secret settings or a password manager.
- Don't share one key between several tools. One key per tool means you can revoke one without breaking the others, and the activity log tells you which tool did what.
- Don't tick every permission "just in case". A key that only reads analytics can't send a message by mistake.
Too many wrong keys
After 10 failed sign-ins from the same internet address within a minute, Luminobot refuses further attempts from that address for the rest of the minute — even with a correct key. If your tool suddenly gets 401 everywhere, check that it isn't retrying an old key in a loop.