# Chaves e escopos

## Criar uma chave

Em **Configurações › API**, um administrador cria a chave e escolhe:

- **Nome:** o sistema que vai usá-la (ex.: “ERP Captei”).
- **Ambiente:** **Produção** age de verdade; **Teste** simula tudo ([Modo teste](/desenvolvedores/modo-teste/)).
- **O que a chave pode fazer:** os escopos abaixo. Uma chamada fora dos escopos da chave volta `403 insufficient_scope`, dizendo em `details.required` quais escopos servem.
- **Disparar campanhas sem esperar aprovação:** sem isso, as campanhas desta chave seguem a regra de aprovação da empresa (o orçamento vale sempre).
- **Vale até** e **só destes endereços IP**, opcionais.

A chave inteira aparece uma única vez, na criação. Guarde-a como uma senha. Chaves de produção começam com `dt_live_`, de teste com `dt_test_`.

## Autenticar

Mande a chave em toda chamada:

```http
Authorization: Bearer dt_live_...
```

`Authorization: ApiKey dt_live_...` também funciona. A empresa vem do endereço (`/v1/c/{empresa}/...`) e precisa ser a da chave.

## Escopos

| Grupo | Escopo | O que permite |
|---|---|---|
| Campanhas | `campaigns:read` | Ver campanhas e resultados |
| Campanhas | `campaigns:write` | Criar e editar rascunhos |
| Campanhas | `campaigns:send` | Disparar, pausar e cancelar |
| Contatos | `contacts:read` | Ver contatos e os valores dos campos |
| Contatos | `contacts:write` | Criar e atualizar contatos |
| Contatos | `fields:read` | Ver a lista de campos |
| Contatos | `fields:write` | Criar campos |
| Contatos | `contacts:delete` | Apagar dados de contatos (LGPD) |
| Modelos | `templates:read` | Ver modelos |
| Modelos | `templates:write` | Criar e enviar modelos para a Meta |
| Mensagens e atendimentos | `messages:send_template` | Enviar modelos |
| Mensagens e atendimentos | `messages:send_text` | Enviar texto e arquivos (janela de 24h) |
| Mensagens e atendimentos | `conversations:read` | Ver atendimentos e mensagens |
| Mensagens e atendimentos | `conversations:write` | Concluir e reabrir atendimentos |
| Fluxos e agenda | `flows:start` | Iniciar fluxos |
| Fluxos e agenda | `appointments:read` | Ver agendamentos |
| Fluxos e agenda | `appointments:write` | Marcar, remarcar e cancelar agendamentos |
| Outros | `webhooks:manage` | Gerenciar avisos (webhooks) |
| Outros | `reports:read` | Ver relatórios e custos |
| Outros | `workspace:read` | Ver números, equipes e etiquetas |
| Outros | `integrations:outboundpro` | Conectar ao OutboundPro Conversas |

## Chaves antigas

Chaves criadas antes dos escopos (`dsf_live_...`) continuam funcionando com o acesso de integração que tinham. Ao escolher escopos para uma delas, ela passa a valer só para eles.

## Segurança

- Uma chave por sistema, com o mínimo de escopos.
- Se uma chave vazar, revogue em Configurações › API: ela para na hora.
- Criação, edição e revogação ficam na Auditoria, com quem fez.