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

# API Key Scopes

> Which permissions your key needs to connect, send, and manage WhatsApp in Notifique.

<Tip>
  An **API Key** is a building access card: each **scope** opens one door. In production, grant only what your integration needs.
</Tip>

## In brief

* Every key belongs to **one workspace**.
* `whatsapp:*` scopes cover instances, sending, and reading on the channel.
* The **`instanceIds`** field restricts **which numbers** the key can use.
* Contacts, tags, and multi-channel templates use **separate** scopes (only if you need them).

General guide: [API Keys](/en/guides/api-key/index). Connection: [Quick Start](/en/whatsapp-api/como-funciona/quick-start).

***

## How to send the key

```http theme={null}
Authorization: Bearer sk_live_xxxxx
```

Alternative: `x-api-key: sk_live_xxxxx`.

<Warning>
  **Empty** scopes on create = **ADMIN** access (everything). In production, always restrict.
</Warning>

***

## Ready-made combinations

<CardGroup cols={2}>
  <Card title="Connect and send" icon="whatsapp">
    `whatsapp:instances:create`, `whatsapp:instances:list`, `whatsapp:send`
  </Card>

  <Card title="Send only" icon="paper-plane">
    `whatsapp:send` + `instanceIds` with the number's instance id
  </Card>

  <Card title="Bot / support" icon="message">
    `whatsapp:send`, `whatsapp:read`
  </Card>

  <Card title="Operate the number" icon="gear">
    `whatsapp:instances:list`, `whatsapp:instances:disconnect`, `whatsapp:instances:delete`
  </Card>
</CardGroup>

***

## Available scopes

<AccordionGroup>
  <Accordion title="whatsapp:instances:list">
    List instances, view details, and get code/QR.
  </Accordion>

  <Accordion title="whatsapp:instances:create">
    Create instance (official or unofficial, with or without shareable link).
  </Accordion>

  <Accordion title="whatsapp:instances:disconnect">
    Disconnect active session.
  </Accordion>

  <Accordion title="whatsapp:instances:delete">
    Remove instance (only when disconnected).
  </Accordion>

  <Accordion title="whatsapp:send">
    Send text, media, templates, buttons, and lists.
  </Accordion>

  <Accordion title="whatsapp:read">
    Sent history, status by id, and inbound messages.
  </Accordion>

  <Accordion title="whatsapp:update">
    Edit sent message.
  </Accordion>

  <Accordion title="whatsapp:cancel">
    Cancel scheduled or queued message.
  </Accordion>

  <Accordion title="whatsapp:delete">
    Delete for everyone.
  </Accordion>

  <Accordion title="whatsapp:groups">
    Groups, participants, invites, and send to group JID. Requires an **unofficial** instance. Guide: [WhatsApp groups](/en/whatsapp-api/grupos/introducao).
  </Accordion>
</AccordionGroup>

***

## Restrict by number (`instanceIds`)

Beyond scope (WHAT), `instanceIds` defines WHERE:

| Situation                           | Result            |
| ----------------------------------- | ----------------- |
| Send on an instance not in the list | **403**           |
| List instances                      | Only allowed ones |
| Inbound and queries                 | Same rule         |

Example: ERP that only sends from support → `whatsapp:send` + `instanceIds: ["clxx123..."]`.

***

## Other scopes (if needed)

| Area                   | Scopes                                                                       |
| ---------------------- | ---------------------------------------------------------------------------- |
| Contacts               | `contacts:read`, `contacts:create`, `contacts:update`, `contacts:delete`     |
| Tags                   | `tags:read`, `tags:create`, `tags:update`, `tags:delete`                     |
| Templates (management) | `templates:read`, `templates:create`, `templates:update`, `templates:delete` |

<Info>
  Sending by template (`POST /v1/templates/send`) uses `whatsapp:send` (and other channels), not `templates:*`. Details: [Templates API scopes](/en/template-api/como-funciona/escopos-da-api-key).
</Info>

***

## Common errors

| HTTP    | Meaning                                        | What to check                       |
| ------- | ---------------------------------------------- | ----------------------------------- |
| **401** | Key missing, invalid, or revoked               | `Authorization: Bearer sk_...`      |
| **403** | Missing scope, blocked instance, or plan limit | Route scope, `instanceIds`, credits |

More codes: [Error responses](/en/guides/conceitos/resposta-de-erros).

***

## Next steps

* [Quick Start](/en/whatsapp-api/como-funciona/quick-start): connect and send
* [Webhook events](/en/whatsapp-api/como-funciona/eventos-do-webhooks): status on your server
* [API Keys](/en/guides/api-key/index): create and rotate keys