Pular para o conteúdo

API e SDK

Autenticação e chaves de API

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

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.

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.

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.

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

Janela do terminal
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.

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.

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.

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:

Janela do terminal
# 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.

  • 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.

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.