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.

Aug 19, 2026

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

  1. Open Settings → Development → API Keys.
  2. Click New key.
  3. Give it a name that identifies it, for example MCP Server - Claude.
  4. Choose the workspace. It is required and cannot be left blank: the key will only see data from that workspace.
  5. Check the scopes that apply (see the table below). If you check none, the key ends up with full access.
  6. Optionally set an expiration date.
  7. 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, and merge_contacts cannot be undone. If you do not want your assistant to be able to delete contacts, do not give it write: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.
  • 404 on a record that does exist: ids are per workspace; the key is tied to a different workspace.

Related articles

Was this helpful?

Related articles

Message us on WhatsApp