Autenticação

Toda chamada a POST /v1/messages exige uma API key de aplicação, enviada no header Authorization:

Authorization: Bearer pln_<ambiente>_<key_id>_<secret>

• <ambiente> é dev, hml ou prd — a key só funciona no ambiente para o qual foi gerada.
• <key_id> é a parte pública da key (permite lookup rápido, não é segredo sozinho).
• <secret> é a parte sensível — mostrada uma única vez no momento da criação. O Planoit nunca guarda o secret em claro, nem devolve ele de volta em nenhuma consulta posterior.

Como solicitar uma key

As API keys são cadastradas por um administrador no backoffice do Planoit, por aplicação:

1. A aplicação em si precisa existir no Planoit (cadastro feito também pelo admin, uma vez).
2. O admin gera a key associada a essa aplicação, escolhendo o ambiente (dev/hml/prd).
3. O secret aparece na tela uma única vez — copie e guarde num cofre de segredos (nunca em código-fonte ou mensagem). Se perder, a única opção é revogar e gerar uma nova.

Se você não tem acesso ao backoffice, peça a um administrador da plataforma.

Erros de autenticação comuns

Situação	HTTP	code
Header Authorization ausente ou sem Bearer	401	API_KEY_MISSING
Token não bate com o formato pln_<env>_<key_id>_<secret>	401	API_KEY_MALFORMED
key_id não encontrado, ou secret não confere	401	API_KEY_INVALID
Key foi revogada	401	API_KEY_REVOKED
Key passou da data de expiração (se houver)	401	API_KEY_EXPIRED
Aplicação dona da key está suspensa	401	APPLICATION_SUSPENDED

Idempotência

Toda chamada de envio também exige o header Idempotency-Key — veja Visão geral.