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

> Permissões para contatos, tags, tópicos, segmentos e campanhas.

<Tip>
  Cinco famílias: **`contacts`**, **`tags`**, **`topics`**, **`segments`**, **`campaigns`**. Campanha também exige escopos de **envio** dos canais (`whatsapp:send`, `sms:send`, …).
</Tip>

Cada **escopo** libera um tipo de operação em Contatos. Use só o que sua integração precisa.

## Como enviar a chave

**Recomendado**

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

**Alternativo**

```http theme={null}
x-api-key: sk_live_sua_chave_aqui
```

<Info>
  A API Key pertence a **um** workspace. Você não acessa outro workspace com a mesma chave.
</Info>

## Combinações comuns

<CardGroup cols={2}>
  <Card title="Só ler base" icon="magnifying-glass">
    `contacts:read`, `tags:read`
  </Card>

  <Card title="Sincronizar CRM" icon="rotate">
    `contacts:read`, `contacts:create`, `contacts:update`, `tags:read`, `tags:create`
  </Card>

  <Card title="Campanhas pela API" icon="paper-plane">
    `campaigns:read`, `campaigns:create`, `campaigns:run` + escopos de envio dos canais
  </Card>

  <Card title="Gestão completa" icon="address-book">
    Todos os `contacts:*`, `tags:*`, `topics:*`, `segments:*`, `campaigns:*`
  </Card>
</CardGroup>

<Warning>
  Lista de escopos **vazia** na criação = acesso **ADMIN**. Em produção, restrinja sempre.
</Warning>

## Contatos (`contacts:*`)

<AccordionGroup>
  <Accordion title="contacts:read">
    Listar e buscar contato por ID.
  </Accordion>

  <Accordion title="contacts:create">
    Criar contato (telefone e/ou e-mail obrigatório).
  </Accordion>

  <Accordion title="contacts:update">
    Editar ficha, tags e campos.
  </Accordion>

  <Accordion title="contacts:delete">
    Excluir contato.
  </Accordion>
</AccordionGroup>

## Tags (`tags:*`)

<AccordionGroup>
  <Accordion title="tags:read">
    Listar e buscar tag.
  </Accordion>

  <Accordion title="tags:create">
    Criar etiqueta reutilizável.
  </Accordion>

  <Accordion title="tags:update">
    Renomear tag.
  </Accordion>

  <Accordion title="tags:delete">
    Excluir tag.
  </Accordion>
</AccordionGroup>

## Tópicos (`topics:*`)

Consentimento por **tema** de marketing (Newsletter, Promoções). Igual ao painel em **Audience → Topics**.

<AccordionGroup>
  <Accordion title="topics:read">
    Listar e buscar tópico.
  </Accordion>

  <Accordion title="topics:create">
    Criar tópico com slug estável.
  </Accordion>

  <Accordion title="topics:update">
    Editar nome, descrição e opt-in padrão.
  </Accordion>

  <Accordion title="topics:delete">
    Excluir tópico.
  </Accordion>
</AccordionGroup>

## Segmentos (`segments:*`)

Públicos com **regras** (tags, campos, tópicos, marketing). Inclui **preview** antes de campanhas.

<AccordionGroup>
  <Accordion title="segments:read">
    Listar, buscar e **preview** (amostra paginada do público).
  </Accordion>

  <Accordion title="segments:create">
    Criar segmento com JSON `version: 1`, `match`, `rules`.
  </Accordion>

  <Accordion title="segments:update">
    Editar regras do segmento.
  </Accordion>

  <Accordion title="segments:delete">
    Excluir segmento.
  </Accordion>
</AccordionGroup>

## Campanhas (`campaigns:*`)

<AccordionGroup>
  <Accordion title="campaigns:read">
    Listar, buscar, **estatísticas** e **destinatários** por execução.
  </Accordion>

  <Accordion title="campaigns:create">
    Criar campanha (opcionalmente com `scheduledFor`).
  </Accordion>

  <Accordion title="campaigns:update">
    Editar campanha e **cancelar** (DRAFT/SCHEDULED → CANCELLED).
  </Accordion>

  <Accordion title="campaigns:delete">
    Excluir campanha.
  </Accordion>

  <Accordion title="campaigns:run">
    **Disparar agora** (Run), enfileira envios nos canais da campanha.
  </Accordion>
</AccordionGroup>

<Warning>
  Disparar campanha exige `campaigns:run` **e** escopos de envio de cada canal (`whatsapp:send`, `sms:send`, `email:send`, `telegram:send`) quando a fila processar mensagens.
</Warning>

## Erros comuns

<AccordionGroup>
  <Accordion title="403: sem escopo">
    Verifique escopo da operação (`Missing scope: contacts:read`, etc.).
  </Accordion>

  <Accordion title="402: limite CRM ou workspace bloqueado">
    Plano ou limite `PLAN_LIMIT_CRM`. Regularize no painel.
  </Accordion>

  <Accordion title="409: duplicata">
    Telefone ou e-mail já cadastrado no workspace.
  </Accordion>
</AccordionGroup>

## Próximos passos

* [Quick Start](/contacts-api/como-funciona/quick-start)
* [Introdução](/contacts-api/como-funciona/introducao)
* [Campanhas](/contacts-api/como-funciona/campanhas-no-painel)
* [Chaves de API (guia)](/guides/api-key/index)