API keys: let your tools and agents work in MB Suite with the permissions you choose

What is an API key for?

An API key acts in MB Suite as the member it represents —you or someone else on the team— and can never do more than that member: if it's someone who only sees their own deals, the API key only sees those deals; if it's a Viewer, the API key can only read. On top of that, you choose which modules it reaches and whether it can only read or also write. Everything done with the API key is recorded under that person's name.

With an API key, your system or a script calls MB Suite's REST API, and Cursor, your own agent or any app that accepts an API key connects through the MCP. Claude, ChatGPT, VS Code and Claude Code don't need one, because they connect by asking for your permission on an MB Suite screen; the step-by-step for each one is in Connect Claude, ChatGPT or Cursor to MB Suite with the MCP. An API key can't create, see or change other API keys: they're managed only from this screen.

Who can create API keys?

Only the owner and the admins see the API keys tab in API & MCP; the rest of the team only sees MCP and Documentation. To create them, the API and the MCP must be turned on in the workspace (see API, MCP and webhooks); if someone turned them off, Create API key stays disabled until they're turned back on. In an Account, it also depends on who pays its subscription: if the Account pays its own, it doesn't need the agency's permission, but it can only create and use its own API keys once that subscription is paid and active (during the free trial, Create API key stays disabled and the screen says why); if your agency pays, the agency has to allow it first. Until then, the Account's API keys tab shows This Account cannot create API keys yet. To allow it:

• In the agency's workspace, go to Settings > Partners.
• On the Account's row, open the three-dot menu and choose View permissions.
• In Module permissions, in the API & MCP block at the bottom, turn on Own API keys. The change saves on its own.

For an Account that pays its own subscription, that switch shows on and can't be turned off: it doesn't need this permission, and its own API keys depend only on its subscription being paid and active.

How do I create an API key?

• Go to Settings > API & MCP: it opens on the API keys tab. Press Create API key.
• If you're in a workspace, choose the Environment at the top: leave Live to work with your real data. Test creates a test API key, which works on a practice organization (what it's for is explained below).
• In Name, write what it's for (for example, “Laura's Cursor” or “Reporting script”), so you can recognize it in the table.
• In Acts as, choose who it represents: by default, you; you can also pick another member of the organization (an admin can't pick an owner). The API key sees and does the same as that person, and this can't be changed later.
• In Permissions, choose for each module No access, Read or Read and write. The CRM comes set to Read: give only what the tool needs. If you give Read and write to a sensitive module —Members, Branding, Accounts, Client Portal, Email Marketing or Integrations—, its row turns amber with a warning, because writing there can change who gets in, your brand, what your clients receive or your connections; in the table, that permission shows in amber too.
• Leave Allow deletions off, unless the tool has to delete records (what changes is explained below).
• Leave Connected mailboxes and calendars off, unless the tool has to read the emails and events linked to the CRM (what it is is explained below). It can only be turned on if an owner has already allowed it for the organization.
• If the API key belongs to an AI agent, turn on API key for an AI agent: whatever it sends over WhatsApp or direct messages is marked as sent by AI, like the Setter's messages, and counts as AI —not as a person— in reports. It doesn't grant any permission: it marks what the API key sends and, because LinkedIn's terms don't allow giving its data to an AI, the API key doesn't receive LinkedIn data.
• Next are the Special permissions: leave them off, unless the API key belongs to an agent you trust that needs them (what they are is explained below).
• If you're in an agency workspace and the API key also has to work in your Accounts, turn on Also access Accounts and choose All Accounts or Choose Accounts. It only reaches the Accounts that the person in Acts as can see.
• In Expiry, choose Never or a term of 30, 90 or 365 days: on that day the API key stops working on its own.
• Press Create API key. Save the API key appears in the same window: copy it with Copy and store it in your password manager. Close with Done, which becomes available once you copy it or check I saved it.

What changes with “Allow deletions”?

When it's off, the API key can't delete anything, even with Read and write: irreversible actions, like deleting deals, people or lists, are only possible if you turn it on, and they also need at least one module with Read and write. Even when the API key can delete, an agent connected through the MCP first has to request a preview of what it's going to delete and confirm it. In the modules that keep a copy, what's deleted stays 30 days in the Trash —what's deleted from the CRM, in the CRM Trash—; what lives outside MB Suite doesn't come back: attached files, WhatsApp templates in Meta and events in your calendar. With each deletion, the tool receives which copy stayed in the Trash, so if the person in Acts as is an owner or an admin, it can restore it on its own. In the table, an API key that can delete carries the Can delete tag.

What is “Connected mailboxes and calendars”?

It's a separate permission, off by default, in its own block below Allow deletions that turns amber while it's on. If you turn it on, the API key reads the emails and events linked to CRM people, companies or deals, only from the mailbox and calendar of the person it represents; never the whole mailbox.

The connected mailbox and calendar are the ones that person connected to the CRM: Gmail, Outlook or IMAP for email, and Google Calendar or Outlook for the calendar. From the mailbox, the API key only reads the conversations linked to a person, company or deal; from the calendar, only the events where the organizer or an outside guest is a person or company in the CRM, plus the bookings from the booking page.

As with everything about the API key, the limit is the person in Acts as: other members' mailboxes and calendars never go out through the API key, even if that person can see them on screen. The API key also needs the CRM on Read or Read and write; with Read and write, it can also link those conversations to a CRM person and archive them or move them back to the inbox (for a Gmail mailbox, in Gmail too). It doesn't delete emails.

To turn it on for an API key, an owner first has to allow it for the organization (how, in the next section). Until then, the API key's switch is disabled, with a notice saying where an owner enables it: the Connected mailboxes and calendars card, in Settings → API & MCP → API keys. In the table, an API key with this permission carries the Connected mailboxes and calendars tag in the Permissions column.

Who allows connected mailboxes and calendars for the organization?

An owner decides, for the whole organization, on the Connected mailboxes and calendars card in the API keys tab, below API version. It applies to API keys and to connected apps, and it comes turned off. Admins see it with the switch disabled and the notice “Only an owner can change this”; the rest of the team doesn't see the API keys tab. To turn it on:

• Go to Settings > API & MCP: it opens on the API keys tab.
• On the Connected mailboxes and calendars card, turn on the switch. Enable connected mailboxes and calendars opens with what it implies: read it and press Enable. The card turns amber and shows the date it was turned on.
• Then give the permission to each API key that needs it, with Edit, and to each app when you authorize it (Connect Claude, ChatGPT or Cursor to MB Suite with the MCP). Turning on the card doesn't give it to any API key or app by itself: each one needs its own permission.

Turning it off doesn't ask for confirmation and cuts immediately: no API key or connected app reads the content of connected mailboxes or calendars, even if it has the permission. You don't need to edit API keys or disconnect apps: the ones that have it are paused —in the table, the amber tag leaves the Permissions column, and opening its permissions shows Connected mailboxes and calendars · paused— and read again as soon as an owner turns the card back on. While it's paused, Edit lets you remove the permission from an API key, but not give it.

What are “Special permissions”?

They're three permissions that go beyond the modules, meant for API keys of agents you trust. They come turned off, in their own block below Permissions, and each one turns amber while it's on. An owner or an admin can give them, never on a Test API key.

Reveal Vault passwords: through the API —never through the MCP—, the API key can request the password of the Vault credentials you choose, today up to 50. When you turn it on, pick them in the selector that appears below: the ones the person in Acts as has no access to show up disabled, because that person must have access to each one, also at the moment of revealing it. The API key also needs at least Read on the Vault: if it doesn't have it, the block warns you and the dialog won't let you save. And there's an hourly limit —today, 30 passwords— for the person it represents, across all their API keys.

Every password the API key reveals is recorded in the credential's Activity as “revealed the secret”, under that person's name and, in gray, with the API key's name. If the API key asks for a credential you didn't give it, or one the person no longer has access to, it gets nothing, and the Activity records it as “tried to reveal the secret without permission”.

Edit live AI agents: the API key sees the instructions and knowledge of the AI agents and can edit them, including the ones working live in the AI Team (the ones holding a seat: see Agents and seats), through the API or the MCP. Every change goes through a preview that the API key itself confirms: giving this permission approves those changes in advance. As with everything else, it never goes beyond what the person in Acts as can see and edit.

Create AI agents: the API key can create AI agents in the organization —and in the Accounts it reaches—, including your own version of one of MB Suite's agents, through the API or the MCP. Every creation goes through a preview that the API key itself confirms: giving this permission approves those creations in advance. A new agent attends no one until a CRM or Social Inbox AI Team seat takes it as its agent —from the app, or when that seat is created or edited through the API or the MCP—, and the person in Acts as must be able to edit agents (a Viewer can't). To see or edit what it created afterwards, the API key also needs Edit live AI agents.

Owners and admins handle special permissions like the rest of the API key: they give them, turn them off and choose the Vault credentials. They can also rotate or reactivate an API key that has them, and rotating it keeps them. The only thing that's still owner-only is managing an API key that acts as an owner: an admin can't create, edit, rotate or reactivate it. To cut it off in an emergency, an admin can still Suspend or Revoke it.

How to use them through the API is in the Documentation tab, in the Permissions and scopes guide.

What is the MCP tool mode?

It's under Advanced, in MCP tool mode, and only matters if you use the API key with the MCP. Compact (recommended) gives the agent five general tools to find, read and run any operation the API key allows. One tool per operation adds a tool for each operation (create a deal, move it to another stage…): more precise, but heavier for the model. If in doubt, keep compact.

How is the API key used?

It goes with every request to MB Suite's REST API (https://api.mb-suite.com/v1) or MCP server (https://mcp.mb-suite.com), in the Authorization header, as Bearer mbs_live_…. That's how your system, Cursor, your own agent or a script use it: the exact MCP configuration is in Connect Claude, ChatGPT or Cursor to MB Suite with the MCP, and the API's, in the Documentation tab. Bulk changes, most deletions and anything that sends something outside MB Suite —a WhatsApp, an email—, changes something on another platform or has a separate cost first go through a preview that the tool itself confirms; how that works is in the same tab.

How do I test without touching my real data?

With a test API key. It starts with mbs_test_ and works only on the workspace's practice organization: a separate organization with example CRM data and its own quota, where nothing leaves MB Suite —emails, WhatsApp messages and PDFs are simulated, and anything else that reaches another platform answers with a 409 error—. It's the place to try your integration or your agent before giving it a Live API key.

• In a workspace, on the API keys tab, find the Practice organization card and press Create test API key (or, in Create API key, set the Environment to Test).
• Fill it in like any other API key. It acts as an owner or an admin of the workspace —they're the ones who get into the practice organization— and it doesn't carry special permissions, Accounts or connected mailboxes and calendars.
• The first time, the practice organization is created on its own and seeded with the example data; the card shows the date of that data and how many test API keys are active.

When you want to start over, Reset test data deletes everything in the practice organization —people, companies, deals, activities, trash, webhook events and deliveries— and seeds the example data again; test API keys and test webhooks are kept. It asks you to confirm with Reset and can't be undone. To also test your webhooks, choose Test on the Webhooks tab: those webhooks only receive what test API keys do (see Webhooks). In the table, a test API key carries the Test tag, and its requests don't show up in your organization's Request log: they stay in the practice one.

What does the API keys tab show?

At the top, the API version block: the organization is pinned to the version in force when it creates its first API key, and each API key keeps its own. That way, when a new version ships, what you already connected doesn't change from one day to the next. Below it are the Connected mailboxes and calendars card (explained above) and, in a workspace, the Practice organization card.

Above the table you see how many active API keys you have out of your plan's maximum: if you reach it, revoke the ones you no longer use (each plan's quotas are on Pricing). Search by name finds an API key, and the Active and suspended / All filter decides whether you also see the revoked, rotated and expired ones. For each API key, the table shows the Name with the beginning of the API key, who it represents (Acts as), a summary of its Permissions, the Accounts it reaches (Only this workspace or Only this Account, All Accounts or how many), its Status, its Last used with the country it was used from, and when it Expires.

The Permissions column shows how many modules the API key reaches and how many it can write to. Below, in amber, the sensitive ones: Can delete, Connected mailboxes and calendars, the special permissions (Can reveal with the number of passwords, Edits live AI agents and Creates AI agents) and write access to a sensitive module; if they don't fit on one line, +N tells you how many more there are. Click the summary to see, below the row, every permission grouped by area, as in the API key editor, and, if the API key can still be edited, the Edit permissions button. In the Name column, next to the beginning of the API key, Test marks the test API keys and, in violet, AI agent marks the API keys of an AI agent: it's a mark, not a permission.

Hover over a status other than Active to see why and what to do.

How do I edit, rotate, suspend or revoke an API key?

It's all in the row's Actions menu (the three dots), and it also works while the API and the MCP are turned off. A Revoked or Rotated API key can no longer be changed: its menu only has View in request log (and a Test one has no menu), and clicking the row opens its permissions.

When editing, Expiry starts on No change, which keeps the expiry the API key already had, and Never removes it. To extend it, or to bring an Expired API key back, choose a new term —it counts from that day— or Never.

Why was an API key suspended on its own?

Because of suspicious use. If an API key piles up many rejected requests within a few minutes, or tries to get into organizations that aren't its own, MB Suite suspends it on its own and sends the owners and admins a notification. It's usually a misconfigured integration —an old API key in a script, a missing permission— or someone using it without permission. Check what happened with View in request log: if you recognize the problem and have already fixed it, Reactivate turns it back on with the same permissions; if you don't recognize it, revoke it.

Because the person left the organization. The API key acts as that person, so it depends on them: if they leave the organization, their API keys are suspended, and if their role or permissions change, the API keys are limited to the new ones. If the person comes back, you can reactivate them; if not, revoke them. So an integration doesn't break when someone leaves, create the API key in the name of whoever will stay in charge.

An API key opens your organization's data —contacts, companies, deals and activities, the metrics of the platforms you connected whose terms allow it (Google Ads, Business Profile, YouTube and TikTok don't; from LinkedIn, only the reports of your ad accounts and pages and your Lead Gen Form leads, and only through the REST API, not through the MCP) and, if you turn on Connected mailboxes and calendars, the emails and events linked to the CRM; with the special permissions, also the passwords you chose from the Vault and your AI agents' instructions— to the tool where you paste it, within the permissions you gave it. Create API keys only for tools you control, with the minimum they need, and revoke them when they're no longer used. The use of API keys and the handling of that data are governed by our Terms and Conditions, our Privacy Notice and our Data Processing Agreement (DPA). Next step: Connect Claude, ChatGPT or Cursor to MB Suite with the MCP.