Permissions and security for the API key used by the MCP server
How to issue the API key for the MCP server, which permissions to check based on what you want your assistant to do, and how to revoke it.
Watch this step in the video · MCP: let an AI operate Omnifox
The MCP server authenticates with an Omnifox personal API key, sent as Authorization: Bearer on every call. Since the AI assistant decides on its own which tool to use, that key should carry only the permissions you actually need.
Create the key
- Open Settings → Development → API Keys.
- Click New key.
- Give it a name that identifies it, for example MCP Server - Claude.
- Choose the workspace. It is required and cannot be left blank: the key will only see data from that workspace.
- Check the scopes that apply (see the table below). If you check none, the key ends up with full access.
- Optionally set an expiration date.
- Save and copy the key right then: that is the only time it is shown in full.
Which scope each group of tools needs
| What you want the assistant to do | Scopes to check |
|---|---|
| Read contacts, search them, see their channels | read:contacts |
| Create, update, tag, or merge contacts | write:contacts |
| Read conversations, messages, and internal notes | read:messages |
| Send messages and notes, assign, close, or snooze | write:messages |
| See connected channels and templates | read:channels |
| Read deals, companies, and pipelines | read:crm |
| Create or move CRM records | write:crm |
| Read projects and boards | read:projects |
| Write to projects and boards | write:projects |
| Register or list webhooks | manage:webhooks |
| All of the above | admin |
If you leave the list empty, the key is equivalent to full access. That is convenient for testing, but for daily use check only what applies.
Recommended combination to start
For an assistant that works the inbox but does not touch billing or settings: read:contacts, write:contacts, read:messages, write:messages, and read:channels.
Revoke access
In API Keys, delete the key. The MCP server stops working on the next call, with a 401. You do not need to touch the AI client's configuration to cut off access.
Tips
- One key per integration. If you share the same key with n8n, a script of your own, and the MCP server, revoking it breaks all of them.
- Set an expiration date on keys you issue for testing.
- Destructive tools do exist:
delete_contact,delete_tag, andmerge_contactscannot be undone. If you do not want your assistant to be able to delete contacts, do not give itwrite:contacts.
If something does not work
401: the key was revoked, expired, or was copied wrong.403: the key is missing that module's scope, or the plan does not include the module.404on a record that does exist: ids are per workspace; the key is tied to a different workspace.
Related articles
Related articles
-
How to connect integrations and external apps
Connect Omnifox with your favorite tools from the integrations catalog in just a few steps.
-
Integrations and API complete guide
Integrations and API in depth, in 30 chapters: API keys, real calls, signed webhooks, n8n, MCP and SDKs, all really working.
-
Connecting Omnifox to Azur, Siigo, Alegra, QuickBooks or another accounting system or ERP
Omnifox doesn't have a native connector for accounting systems or ERPs today. Here's how to connect them anyway with workflows, the HTTP node, n8n, Make, Zapier or the API, with examples.
-
Generate and use API keys and webhooks
Create API keys to access Omnifox programmatically and set up webhooks to receive real-time events.
-
Getting started with integrations (webhook / OAuth / API key)
Connect Omnifox with your other tools: what's available today, what's coming soon, and when to use a webhook, an OAuth connection or an API key.