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
  1. How a key is sent
  2. What a key can reach
  3. Choosing permissions
  4. Replacing a key
  5. Revoking a key
  6. Keys versus AI agent tokens
  7. What not to do
  8. Too many wrong keys

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 plain http:// 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.

  1. Create a new key with the same workspace, accounts and permissions.
  2. Put the new key into your tool and check that it works.
  3. 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.