Permissions
A key has a set of permissions. You choose a level when you create the key and can tick single permissions. A call with a missing permission fails with insufficient_scope.
| Level | What it means | Permissions |
|---|---|---|
| Read | Read everything that is not secret. Changes nothing, with one exception: it can request a contact export, which creates a file with personal data. | 17 |
| Draft | Everything in Read, plus create and change drafts. Nothing reaches other people. | 25 |
| All | Everything except deleting and the plan. It includes the permissions with their own checkbox; in the app you can untick them. | 38 |
Permissions with "yes" in the column Own checkbox reach other people or reveal secrets. The level All includes them, but in the app each of them has its own checkbox that you can untick. The levels Read and Draft never include them.
There are no permissions for deleting. See what keys can never do.
Permission and effect are two different things. A permission says which calls a key may make. An effect says what a call does. create_contact_export needs the permission contacts:read, because it reads your contacts. It still creates a new file with their names, phone numbers and email addresses. That is why MCP marks the tool export_contacts as a write tool (readOnlyHint is false). A key with only the level Read can therefore start an export.
| Permission | What it allows | Read | Draft | All | Own checkbox | Used by |
|---|---|---|---|---|---|---|
contacts:read | Read contacts, tags and contact export requests (phone numbers included). | yes | yes | yes | - | get_optin_status, search_contacts, get_contact, list_tags, create_contact_export, get_contact_export |
contacts:write | Create and change contacts, add and remove tags. Never sets a contact to confirmed. | - | yes | yes | - | create_contact, update_contact, tag_contacts, create_conversation_note |
contacts:unsubscribe | Unsubscribe a contact from all marketing messages. Cannot be undone through the API; MCP asks for a confirmation. | - | - | yes | - | unsubscribe_contact |
sends:read | Read the delivery status of sends. | yes | yes | yes | - | get_send |
sends:create | Send a single message (free text or template) and send opt-in confirmations. | - | - | yes | - | create_optin_confirmations, send_text_message, send_template_message |
inbox:read | Read conversations and messages. | yes | yes | yes | - | list_conversations, get_conversation, list_messages, list_events |
inbox:write | Assign, close, mark as read and hand over conversations; add internal notes. | - | yes | yes | - | update_conversation, create_conversation_note |
templates:read | Read message templates. | yes | yes | yes | - | list_templates, get_template |
templates:write | Create and change template drafts. | - | yes | yes | - | create_template, update_template |
templates:submit | Submit templates to WhatsApp for approval. | - | - | yes | yes | create_template_submissions |
newsletters:read | Read newsletters, previews and progress. | yes | yes | yes | - | list_newsletters, get_newsletter, get_newsletter_send_preview |
newsletters:write | Create and change newsletter drafts and create send plans. | - | yes | yes | - | create_newsletter, update_newsletter |
newsletters:send | Send, schedule, pause, resume and cancel newsletters in one step. Needs an idempotency key. | - | - | yes | yes | create_optin_confirmations, send_newsletter, control_newsletter |
newsletters:test | Send a test newsletter to any phone number (approved templates only, never to unsubscribed contacts). | - | - | yes | - | send_test_newsletter |
followups:read | Read follow-up sequences. | yes | yes | yes | - | list_followup_sequences, get_followup_sequence |
followups:write | Change follow-up sequences and their steps. | - | yes | yes | - | create_followup_sequence, update_followup_sequence |
automations:read | Read automations and their runs. | yes | yes | yes | - | get_automation_catalog, list_automations, get_automation, list_automation_runs |
automations:write | Create and change automations as drafts. Activating one or changing a running one also needs automations:run. | - | yes | yes | - | create_automation, update_automation, set_automation_status |
automations:run | Start an automation with data (live run). | - | - | yes | - | create_automation_run |
hooks:read_secret | Read the secret of an automation's inbound web address. | - | - | yes | yes | get_inbound_webhook |
landing:read | Read the landing page and its catalog. | yes | yes | yes | - | get_landing_catalog, get_landing_page |
landing:write | Apply edit operations to the landing page (does not publish). | - | yes | yes | - | apply_landing_page_ops, restore_landing_page |
landing:publish | Publish a draft of the landing page. The live page is never taken offline; the previous version can be restored. | - | - | yes | yes | publish_landing_page |
ai:settings_read | Read the SmartChat AI reply settings and the learned answers. | yes | yes | yes | - | get_ai_reply_settings, list_learned_answers |
ai:settings | Change the SmartChat AI reply settings and learned answers. Turning the AI reply on lets SmartChat answer your customers on its own, so this right is only in the level "all". | - | - | yes | - | update_ai_reply_settings, create_learned_answer, update_learned_answer |
knowledge:read | Search the knowledge and list knowledge documents. | yes | yes | yes | - | search_knowledge, list_knowledge_documents |
knowledge:write | Upload knowledge documents (analysis with a model stays in the app). | - | - | yes | - | - |
media:read | Read the media library. | yes | yes | yes | - | list_media |
media:write | Upload media files. | - | yes | yes | - | create_media |
settings:read | Read the business profile, brand, content rules and follow-up timing. | yes | yes | yes | - | get_business_profile, get_followup_settings |
settings:write | Change the business profile, brand, content rules, template style, test number and follow-up timing. Never legal texts, tracking or connections. Only in the level "all". | - | - | yes | - | update_business_profile, update_followup_settings |
webhooks:read | Read outgoing webhook endpoints and deliveries. | yes | yes | yes | - | list_webhook_endpoints, get_webhook_endpoint, list_webhook_deliveries |
webhooks:write | Create, change and unsubscribe outgoing webhook endpoints. | - | - | yes | - | create_webhook_endpoint, update_webhook_endpoint, unsubscribe_webhook_endpoint, rotate_webhook_secret, enable_webhook_endpoint, test_webhook_endpoint, replay_webhook_events, redeliver_webhook_delivery |
connections:read | Read connected apps (status only) and the names of vault secrets, never their values. | yes | yes | yes | - | - |
connections:run | Run actions of connected apps. Actions that delete data in the app stay blocked. | - | - | yes | yes | - |
stats:read | Read statistics without personal data. | yes | yes | yes | - | get_stats |
team:read | Read team members (name and role). | yes | yes | yes | - | list_team_members |
account:read | Read the account overview (setup, credit balance). | yes | yes | yes | - | get_account_overview |
billing:read | Read plan, invoices and credit history. | - | - | - | - | get_billing, list_invoices, list_credit_history |