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

# Autenticação

> Como enviar a chave de API nas requisições

Toda requisição precisa apresentar a chave de API em um **cabeçalho HTTP**. Não há autenticação por corpo da requisição nem por query string.

<Warning>
  **Se você seguiu uma versão anterior desta documentação, sua integração não funciona.** Aquela versão instruía a enviar a chave no corpo da requisição, num formato que **nunca foi aceito pela API** — requisições assim sempre receberam `401`. Use o cabeçalho abaixo. Os detalhes da mudança estão em [Migração das rotas antigas](/tutoriais/api/migracao-v2-api-whatsapp).
</Warning>

## Forma padrão

```bash theme={null}
curl 'https://api.wizebot.com.br/api/v1/whatsapp/ping' \
  -H 'Authorization: Bearer API-KEY'
```

É a forma usada em todos os exemplos desta documentação, e a que a maioria dos clientes HTTP monta por padrão quando você configura um token.

## Formas alternativas

As duas formas abaixo também são aceitas e produzem exatamente o mesmo resultado. Use-as se o seu cliente já estiver montado assim.

<CodeGroup>
  ```bash Cabeçalho dedicado theme={null}
  curl 'https://api.wizebot.com.br/api/v1/whatsapp/ping' \
    -H 'x-api-key: API-KEY'
  ```

  ```bash Esquema ApiKey theme={null}
  curl 'https://api.wizebot.com.br/api/v1/whatsapp/ping' \
    -H 'Authorization: ApiKey API-KEY'
  ```
</CodeGroup>

<Note>
  As três formas são equivalentes, inclusive para o limite de requisições: a mesma chave consome o mesmo saldo, independentemente do cabeçalho escolhido. Não há ganho em alternar entre elas.
</Note>

## A API é de servidor para servidor

<Note>
  Não chame esta API a partir de um navegador, aplicativo móvel ou qualquer código que o usuário final consiga inspecionar.
</Note>

Há duas razões:

1. **A chave dá acesso total à sua conta.** Exposta no navegador, ela pode ser lida por qualquer visitante.
2. **Tecnicamente não funciona.** A política de CORS do servidor não libera os cabeçalhos de autenticação para origens de navegador, então a requisição de verificação prévia falha antes mesmo de a chamada sair.

O caminho correto é o seu servidor chamar a API e o seu front-end chamar o seu servidor.

## Obter a chave

A chave é gerada no painel, em **Configurações → API Keys**. Ela é exibida uma única vez, no momento da criação.

<Warning>
  Guarde a chave em local seguro e nunca a coloque em código-fonte público, aplicativo móvel ou página web.
</Warning>

## Ciclo de vida da chave

| Propriedade   | Comportamento                                                                       |
| ------------- | ----------------------------------------------------------------------------------- |
| Armazenamento | Guardamos apenas o resumo criptográfico. A chave não é recuperável depois de criada |
| Exibição      | Apenas uma vez, no momento da criação                                               |
| Expiração     | Opcional, definida na criação                                                       |
| Revogação     | Imediata. Uma chave revogada passa a receber `401` na requisição seguinte           |
| Escopo        | A chave pertence a uma empresa e só enxerga os dados dela                           |

<Note>
  Se a chave vazar, revogue-a no painel e gere outra. Não existe rotação parcial: a chave antiga para de funcionar assim que é revogada.
</Note>

## Erros de autenticação

Falha de autenticação segue o mesmo envelope de erro de qualquer outro problema. Veja [Respostas e erros](/tutoriais/api/respostas-e-erros-api-whatsapp).

```json theme={null}
{
  "success": false,
  "statusCode": 401,
  "timestamp": "2026-09-08T19:30:00.000Z",
  "path": "/api/v1/whatsapp/ping",
  "method": "GET",
  "message": { "message": "Não autorizado" },
  "errorId": "ERR-MTT63UQF-5WH1EX"
}
```

<Note>
  O `401` é o mesmo para chave ausente, chave inválida, chave revogada, chave expirada e empresa inativa. Essa indistinção é proposital — devolver o motivo exato permitiria descobrir quais chaves existem.
</Note>

## Testar a conexão

O endpoint `GET /ping` confirma que a chave é válida sem produzir efeito nenhum. Ele tem limite de 5 requisições por minuto, então serve para verificação pontual e para monitoramento em intervalos de 30 segundos ou mais — não para verificação a cada poucos segundos.

```bash theme={null}
curl 'https://api.wizebot.com.br/api/v1/whatsapp/ping' \
  -H 'Authorization: Bearer API-KEY'
```