# Scopes and permissions

Part of the InboxWA API reference: https://inboxwa.online/docs/api . Full reference as one document: https://inboxwa.online/docs/api.md . OpenAPI: https://inboxwa.online/openapi.json

A key carries `all`, or any combination of the scopes below. Scopes choose how much of the workspace the key reaches, from one screen to everything.

A key can never do more than the admin who created it. Its effective access is the creator’s permissions intersected with its scopes.

## Read-only scopes

A `:read` scope lets a key call GET endpoints in that area and nothing else. A key made only of read scopes is a read-only key: every write method is refused with `read_only_key`, on every route, including routes that carry no permission check of their own. Use these for dashboards and reports.

| Scope | Read-only variant | What it covers |
| --- | --- | --- |
| `inbox` | `inbox:read` | Read chats and messages; claim, release, transfer, snooze, label and note conversations. |
| `contacts` | `contacts:read` | Contacts, leads and deals, tags, attributes, segments, import. |
| `campaigns` | `campaigns:read` | Bulk send, scheduled sends, campaign control. |
| `automations` | `automations:read` | Workflows, auto-replies, drip sequences and their analytics. |
| `templates` | `templates:read` | Message templates and WhatsApp Flows. |
| `analytics` | `analytics:read` | Dashboards, engagement and message statistics. |
| `whatsapp_api` |  | Send through the Meta Cloud API. Layered with templates and campaigns. |
| `contacts_delete` |  | Hard delete and bulk delete of contacts. |
| `contacts_export` |  | Bulk export of contacts. |
| `campaign_approve` |  | Send directly and approve or reject pending bulk sends. |
| `templates_delete` |  | Delete WhatsApp templates. |
| `inbox_assigned_only` |  | Restricts inbox reads and sends to chats assigned to the key creator. |
| `ai_agent` | `ai_agent:read` | Bot configuration: knowledge base, pricing, behaviour, on and off. |
| `ai_kb_edit` |  | Change the FAQs the bot answers from. |
| `ai_pricing_edit` |  | Change the pricing sheets the bot quotes from. |
| `ai_behavior_edit` |  | Change persona, system prompt and response style. |
| `ai_audit_view` |  | Read AI usage, cost and handover audit trail. |
| `ai_provision` |  | Turn the bot on or off for the workspace. |
| `team_management` | `team_management:read` | Roster, invites, roles, performance, goals, SLA, audit log. |
| `team_remove_member` |  | Remove members from the workspace. |
| `audit_view` |  | Read the team audit log. |
| `settings` | `settings:read` | Workspace settings, webhooks, integrations, API keys (list). |
| `billing_view` |  | Plan, usage, credits and invoices. |
| `billing_manage` |  | Change plan, payment methods and top up credits. |

> **Reporting API access** The reporting calls accept `inbox` or `contacts` (and their `:read` variants) for chat content, and `inbox`, `team_management` or `analytics` (and `:read`) for team accountability data such as who opened a chat and how fast replies were.