> ## 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.

# Escopos da API Key

> Quais permissões sua chave precisa para conectar, enviar e gerenciar WhatsApp no Notifique.

<Tip>
  A **API Key** é o cartão de acesso do prédio: cada **escopo** abre uma porta. Em produção, libere só o que sua integração precisa.
</Tip>

## Em poucas palavras

* Toda chave pertence a **um workspace**.
* Escopos `whatsapp:*` cobrem instâncias, envio e leitura do canal.
* O campo **`instanceIds`** restringe **quais números** a chave pode usar.
* Contatos, tags e templates multicanal usam escopos **à parte** (só se precisar).

Guia geral: [Chaves de API](/guides/api-key/index). Conexão: [Quick Start](/whatsapp-api/como-funciona/quick-start).

***

## Como enviar a chave

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

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

<Warning>
  Escopos **vazios** na criação = acesso **ADMIN** (tudo). Em produção, restrinja sempre.
</Warning>

***

## Combinações prontas

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

  <Card title="Só enviar" icon="paper-plane">
    `whatsapp:send` + `instanceIds` com o id do número
  </Card>

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

  <Card title="Operar o número" icon="gear">
    `whatsapp:instances:list`, `whatsapp:instances:disconnect`, `whatsapp:instances:delete`
  </Card>
</CardGroup>

***

## Escopos disponíveis

<AccordionGroup>
  <Accordion title="whatsapp:instances:list">
    Listar instâncias, ver detalhes e obter código/QR.
  </Accordion>

  <Accordion title="whatsapp:instances:create">
    Criar instância (oficial ou não oficial, com ou sem link compartilhável).
  </Accordion>

  <Accordion title="whatsapp:instances:disconnect">
    Desconectar sessão ativa.
  </Accordion>

  <Accordion title="whatsapp:instances:delete">
    Remover instância (somente desconectada).
  </Accordion>

  <Accordion title="whatsapp:send">
    Enviar texto, mídia, template, botões e listas.
  </Accordion>

  <Accordion title="whatsapp:read">
    Histórico de enviadas, status por id e mensagens recebidas (inbound).
  </Accordion>

  <Accordion title="whatsapp:update">
    Editar mensagem enviada.
  </Accordion>

  <Accordion title="whatsapp:cancel">
    Cancelar agendada ou na fila.
  </Accordion>

  <Accordion title="whatsapp:delete">
    Apagar para todos.
  </Accordion>

  <Accordion title="whatsapp:groups">
    Grupos, participantes, convites e envio para JID de grupo. Requer instância **não oficial**. Guia: [Grupos WhatsApp](/whatsapp-api/grupos/introducao).
  </Accordion>
</AccordionGroup>

***

## Limitar por número (`instanceIds`)

Além do escopo (o **que**), `instanceIds` define **onde**:

| Situação                         | Resultado        |
| -------------------------------- | ---------------- |
| Envio em instância fora da lista | **403**          |
| Listar instâncias                | Só as permitidas |
| Inbound e consultas              | Mesma regra      |

Exemplo: ERP que só envia pelo suporte → `whatsapp:send` + `instanceIds: ["clxx123..."]`.

***

## Outros escopos (se precisar)

| Área               | Escopos                                                                      |
| ------------------ | ---------------------------------------------------------------------------- |
| Contatos           | `contacts:read`, `contacts:create`, `contacts:update`, `contacts:delete`     |
| Tags               | `tags:read`, `tags:create`, `tags:update`, `tags:delete`                     |
| Templates (gestão) | `templates:read`, `templates:create`, `templates:update`, `templates:delete` |

<Info>
  Enviar por template (`POST /v1/templates/send`) usa `whatsapp:send` (e outros canais), não `templates:*`. Detalhes: [API de Templates](/template-api/como-funciona/escopos-da-api-key).
</Info>

***

## Erros comuns

| HTTP    | Significado                                        | O que conferir                          |
| ------- | -------------------------------------------------- | --------------------------------------- |
| **401** | Chave ausente, inválida ou revogada                | `Authorization: Bearer sk_...`          |
| **403** | Sem escopo, instância bloqueada ou limite do plano | Escopo da rota, `instanceIds`, créditos |

Mais códigos: [Respostas de erro](/guides/conceitos/resposta-de-erros).

***

## Próximos passos

* [Quick Start](/whatsapp-api/como-funciona/quick-start): conectar e enviar
* [Eventos dos webhooks](/whatsapp-api/como-funciona/eventos-do-webhooks): status no seu servidor
* [Chaves de API](/guides/api-key/index): criar e rotacionar chaves