> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lazyapp.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Scopes

> What each scope grants.

Every API key carries scopes. A call outside them returns `403`.

| Scope | Grants |
| - | - |
| `messages:send` | Send messages, create and update contacts, send events, trigger workflows, start broadcasts |
| `messages:read` | Read messages, contacts, conversations, workflows, broadcasts, capabilities, scheduled messages |
| `templates:read` | List and read templates and event-to-template mappings |
| `templates:write` | Create, sync and delete templates; provision event mappings and automation packs |
| `media:write` | Upload and delete media |
| `webhooks:write` | Manage webhook endpoints and read deliveries |
| `flows:write` | Manage WhatsApp Flows and read their responses |
| `customers:write` | Manage platform customers, setup links and embed tokens |
| `customers:act` | Act on behalf of a platform customer without managing them |
| `billing:read` | Read billing and usage, pricing facts and volume tiers |
| `billing:write` | Change a WhatsApp account's billing currency |
| `connections:write` | Change WhatsApp numbers and their account: register, two-step PIN, display name, blue tick, QR codes, conversation starters, opt-in links, adding numbers |
| `payments:write` | Manage payment setups and gateway accounts, and refund payments |
| `catalog:write` | Add, change and remove products in the connection's Meta catalog |

## By endpoint group

| Endpoints | Read scope | Write scope |
| - | - | - |
| Messages | `messages:read` | `messages:send` |
| Contacts | `messages:read` | `messages:send` |
| Conversations | `messages:read` | — |
| Events | `messages:read` | `messages:send` |
| Broadcasts | `messages:read` | `messages:send` |
| Workflows | `messages:read` | `messages:send` |
| Capabilities | `messages:read` | — |
| Connections (numbers, health, blue tick, QR codes, opt-in links) | `messages:read` | `connections:write` |
| Connections (business profile text, blocked users) | `messages:read` | `messages:send` |
| Templates | `templates:read` | `templates:write` |
| Event mappings / automation packs | `templates:read` | `templates:write` |
| Media | `messages:read` | `media:write` |
| Webhooks | `webhooks:write` | `webhooks:write` |
| Flows | `flows:write` | `flows:write` |
| Verify — send | — | `messages:send` |
| Verify — verify | `messages:read` | — |
| Platform | `customers:write` or `customers:act` | `customers:write` |
| Payments — requests, status, lookup | `messages:read` | `messages:send` |
| Payments — setups, gateway accounts, refunds | `messages:read` (list setups) | `payments:write` |
| Payment templates | — | `templates:write` |
| Shop settings | `messages:read` | `messages:send` |
| Catalog products and changes | `messages:read` | `catalog:write` |
| Pricing and currency change | `billing:read` | `billing:write` |
| WhatsApp analytics | `messages:read` | `templates:write` (template insights) |
| Ad results | `messages:read` | — |

> [!NOTE]
>
> Media metadata reads use `messages:read`, while uploads and deletes need `media:write`.
> A key that only sends messages referencing existing media does not need `media:write`.

## Choosing

Grant the narrowest set that works, and use separate keys for separate jobs. A key that only delivers OTPs needs `messages:send` and nothing else — so if it leaks, it cannot read your conversation history.

Keys can also be restricted to specific phone numbers or IP addresses. See [Authentication](https://docs.lazyapp.in/authentication.md#restrictions).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.