API e SDK
Autenticação e chaves de API
Como criar, usar e proteger as chaves que autenticam a API /v1.
Criar a chave no painel
Seção intitulada “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 |
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
Seção intitulada “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) |
| 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 |
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
Seção intitulada “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
Seção intitulada “Authorization: Bearer”Mande a chave no cabeçalho Authorization com o esquema Bearer, em toda requisição:
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. Também não há chave em query string.
Erros de autenticação
Seção intitulada “Erros de autenticação”Todo erro usa o corpo único da API, com um code estável:
{ "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 |
Faltou o cabeçalho Authorization: Bearer |
| 401 | invalid_api_key |
A chave não existe ou foi revogada |
| 401 | api_key_expired |
A validade da chave acabou |
| 401 | api_key_disabled |
A chave foi desativada no painel |
| 403 | insufficient_permissions |
A chave não tem a permissão que a rota exige |
| 403 | connection_not_allowed |
A chave está presa a outras conexões |
| 403 | 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
Seção intitulada “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 é só leitura e não envia requisições.
Girar uma chave
Seção intitulada “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:
# criar chave de uma conexãocurl -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"]}'
# girarcurl -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"}'
# revogarcurl -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.
Boas práticas
Seção intitulada “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.
X-Request-Id para suporte
Seção intitulada “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.