# Autenticação e chaves de API

> Como criar, usar e proteger as chaves que autenticam a API /v1.

## Criar a chave no painel

Em **Chaves de API → Criar chave**, preencha:

| Campo | O que é |
|---|---|
| **Nome** | Até 32 caracteres, para reconhecer a chave depois (`produção`, `crm`) |
| **Permissões** | `send` (enviar mensagens), `read` (ler conexões, conversas e logs), `templates` (criar e editar templates) e `admin` (tudo). Marque só o que a integração usa |
| **Conexões** | **Todas as conexões** ou só as selecionadas. Uma chave presa a conexões não enxerga as outras |
| **Validade** | 30, 90, 180 ou 365 dias, ou **Não expira** |
| **Limite por minuto** | De 1 a 6.000 requisições por minuto (padrão: 600). Veja [Limites](/api/limits/) |

Dono, admin e dev criam chaves. Só dono e admin dão a permissão `admin`. Depois de criada, a chave pode ser editada (nome, permissões, conexões, limite), desativada, reativada ou revogada.

## Tipos de chave

|  | Chave de organização (`mj_`) | Chave de conexão (`mjc_`) |
|---|---|---|
| Onde criar | **Chaves de API**, no nível da organização | Aba **Chaves de API** da conexão |
| Alcance | Qualquer conexão da org; `connection_id` obrigatório nas rotas de mensagem | Só a conexão dela; `connection_id` é opcional (se enviado e diferente, 403 [`connection_not_allowed`](/errors#connection_not_allowed)) |
| Destinos | Globais e de qualquer conexão | Só os da própria conexão, nunca globais |
| Conexões | Listar, alterar e desconectar | Ler e alterar a própria; não desconecta |
| Links de conexão | Sim | 403 [`organization_key_required`](/errors#organization_key_required) |
| Gerir chaves de conexão pela `/v1` | Sim, com a permissão `admin` | Não |
| Eventos, entregas, logs e custos | A org inteira | Só os da conexão (mais eventos da WABA) |
| `GET /v1/me` | `api_key.kind = "org"`, `connection_id` e `connection` nulos | `api_key.kind = "connection"`, com `connection_id` e `connection { id, channel, label }` |

As permissões (`send`, `read`, `templates`, `commerce`, `admin`) valem para os dois tipos. Use uma chave de conexão por integração: ela só enxerga o número dela e dispensa o `connection_id`. Chaves de organização antigas presas a várias conexões continuam funcionando, mas o painel não oferece mais essa opção.

Templates, flows e catálogos pertencem à WABA: a chave de conexão que os altera afeta também as conexões irmãs da mesma WABA.

## A chave aparece uma vez

O valor completo, que começa com `mj_` (organização) ou `mjc_` (conexão), só aparece no diálogo de criação. O Messajo guarda apenas um hash: nem o painel, nem o suporte conseguem mostrá-la de novo. Perdeu? Crie outra e revogue a antiga.

Para reconhecer a chave depois, o painel mostra o **prefixo visível**, os 10 primeiros caracteres (por exemplo, `mj_A1b2c3d`). O mesmo prefixo volta no campo `api_key.start` de `GET /v1/me`.

## Authorization: Bearer

Mande a chave no cabeçalho `Authorization` com o esquema `Bearer`, em toda requisição:

```bash
curl https://api.messajo.com/v1/me \
  -H "Authorization: Bearer $MESSAJO_API_KEY"
```

Cookie de sessão do painel **nunca** autentica a API `/v1`: uma requisição só com cookie recebe [`missing_api_key`](/errors#missing_api_key). Também não há chave em query string.

## Erros de autenticação

Todo erro usa o corpo único da API, com um `code` estável:

```json
{
  "error": {
    "code": "missing_api_key",
    "message": "Missing API key: send Authorization: Bearer <key>",
    "meta_code": null,
    "retryable": false,
    "request_id": "req_0193a1b2c3d47e8f9a0b1c2d3e4f5a6b",
    "docs_url": "https://docs.messajo.com/errors#missing_api_key"
  }
}
```

| Status | `code` | Quando |
|---|---|---|
| 401 | [`missing_api_key`](/errors#missing_api_key) | Faltou o cabeçalho `Authorization: Bearer` |
| 401 | [`invalid_api_key`](/errors#invalid_api_key) | A chave não existe ou foi revogada |
| 401 | [`api_key_expired`](/errors#api_key_expired) | A validade da chave acabou |
| 401 | [`api_key_disabled`](/errors#api_key_disabled) | A chave foi desativada no painel |
| 403 | [`insufficient_permissions`](/errors#insufficient_permissions) | A chave não tem a permissão que a rota exige |
| 403 | [`connection_not_allowed`](/errors#connection_not_allowed) | A chave está presa a outras conexões |
| 403 | [`organization_key_required`](/errors#organization_key_required) | A rota é só de chave de organização e a chave é de conexão |

Nenhum desses erros se resolve repetindo a chamada (`retryable: false`): corrija a chave ou as permissões dela.

## Testar no /reference

A referência interativa fica em `https://api.messajo.com/reference`.Ali você cola a chave em **Authentication** e usa **Test request** para chamar as rotas de verdade, como `GET /v1/me`.

A chamada sai do seu navegador para o próprio servidor, na mesma origem, sem passar por proxy de terceiros. A [referência destas docs](/reference) é só leitura e não envia requisições.

## Girar uma chave

No painel, **Girar** cria uma chave nova com o mesmo nome, tipo, permissões, conexão e limite, e mostra o novo valor uma única vez. A chave antiga continua valendo por uma **carência**: **24 horas** (padrão) ou **agora**, que a encerra na hora. A carência nunca passa da validade original. Chave desativada ou vencida não pode ser girada.

Pela `/v1`, uma chave de organização com `admin` cria, gira e revoga só **chaves de conexão** (`grace`: `24h` ou `now`). Chaves de organização são giradas no painel; a `/v1` devolve 404 `not_found` para elas:

```bash
# criar chave de uma conexão
curl -X POST https://api.messajo.com/v1/connections/$CONNECTION_ID/api-keys \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "crm", "permissions": ["send", "read"]}'

# girar
curl -X POST https://api.messajo.com/v1/api-keys/$KEY_ID/rotate \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"grace": "24h"}'

# revogar
curl -X DELETE https://api.messajo.com/v1/api-keys/$KEY_ID \
  -H "Authorization: Bearer $MESSAJO_API_KEY"
```

A resposta da rotação traz o segredo novo e `previous_key_expires_at`, o fim da carência da antiga. Os campos completos estão na [referência](/reference).

## Boas práticas

- **Variável de ambiente ou cofre de segredos**, nunca no código nem no repositório.
- **Nunca no navegador nem no app móvel.** Qualquer pessoa extrai a chave de um front-end. Chame o Messajo do seu back-end.
- **Uma chave por integração**, com o mínimo de permissões e, se der, presa às conexões que usa. Vazou uma, você revoga só ela.
- **Validade definida** para chaves de teste e de terceiros.
- **Girar sem parar:** crie a chave nova, troque na integração, confira o **último uso** da antiga no painel e só então revogue. O **último uso** é atualizado no máximo a cada ~5 s por réplica e o contador de requisições não é exato por chamada (a verificação da chave é cacheada por 5 s).
- **Vazou?** Revogue na hora. A próxima chamada com ela já recebe [`invalid_api_key`](/errors#invalid_api_key).

## X-Request-Id para suporte

Toda resposta, de sucesso ou de erro, traz o cabeçalho `X-Request-Id` (`req_…`). O mesmo valor aparece em `request_id` no corpo dos erros e de `GET /v1/me`.

Grave esse valor no log da sua integração. Ao pedir ajuda, mande o `X-Request-Id`: com ele o suporte acha a chamada exata, sem que você precise mandar a chave.
