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

# Autenticação

> Header Bearer, escopos por token e os códigos de erro de 401 e 403.

Toda requisição à API precisa do header `Authorization` com um token Bearer:

```bash theme={null}
curl https://sua-instancia.whatix.cloud/wapi/v1/connections \
  -H "Authorization: Bearer wtx_live_SEU_TOKEN"
```

O token começa com `wtx_live_` e identifica a conta e os escopos liberados. Não existe autenticação por usuário/senha nem por cookie — só o token.

## Onde criar

Só um admin cria tokens, em **API** (menu lateral) → aba **Tokens** → **Novo token**. Ao criar, você escolhe os escopos — cada um aparece no painel com um rótulo (ex. "Ler conexões" corresponde a `connections:read`). O valor completo do token só aparece uma vez, no momento da criação — guarde-o num cofre de segredos, não em planilha ou chat.

## Escopos

Cada token tem um conjunto de escopos. O endpoint recusa a chamada com 403 se o escopo exigido não estiver marcado.

| Escopo | Libera |
| - | - |
| `conversations:read` | Listar e consultar conversas |
| `messages:read` | Listar mensagens e consultar status de entrega |
| `messages:send` | Enviar mensagens |
| `connections:read` | Listar conexões (canais) da sua conta |
| `contacts:read` | Listar e consultar contatos e tags |
| `contacts:write` | Criar, atualizar contatos e sincronizar tags |
| `cards:read` | Listar e consultar cards, pipelines e motivos de perda |
| `cards:write` | Criar cards e mover de etapa |
| `flows:trigger` | Disparar flows do FlowBuilder |

Um escopo `write` sempre satisfaz o `read` correspondente: um token com `contacts:write` também lê contatos, sem precisar marcar `contacts:read` também.

## Validade e rotação

O token suporta expiração (`ERR_TOKEN_EXPIRED` existe pra isso), mas a tela de criação atual não tem campo de validade — na prática, todo token criado hoje pelo painel é eterno até ser revogado. Para rotacionar sem downtime:

<Steps>
  <Step title="Crie o novo token">
    Mesmos escopos do token atual (ou os que você realmente usa).
  </Step>

  <Step title="Troque no cliente">
    Atualize a variável de ambiente ou o cofre de segredos da sua integração com o novo valor.
  </Step>

  <Step title="Revogue o antigo">
    Só depois de confirmar que o cliente já usa o novo token. Revogar é imediato e não tem volta.
  </Step>
</Steps>

## Erros de autenticação e permissão

Toda falha de autenticação vem com um `code` no corpo da resposta — trate por ele, nunca pelo texto de `error`.

| Código | HTTP | Quando acontece |
| - | - | - |
| `ERR_TOKEN_MISSING` | 401 | Header `Authorization` ausente |
| `ERR_TOKEN_INVALID` | 401 | Token não existe ou está mal formado |
| `ERR_TOKEN_REVOKED` | 401 | Token foi revogado no painel |
| `ERR_TOKEN_EXPIRED` | 401 | Passou da validade definida na criação |
| `ERR_SCOPE_MISSING` | 403 | Token válido, mas sem o escopo exigido pelo endpoint |

<Warning>Nunca exponha o token em código de front-end, app mobile ou qualquer lugar acessível pelo navegador do usuário final. O token dá acesso total aos escopos marcados — trate como uma senha de admin.</Warning>