Chaves de API — listar, regenerar, rotacionar
Toda requisição à API do Pilot Status exige uma chave de API em um destes cabeçalhos:
x-api-key: a chave bruta (ps_...)x-api-key-id: o ID da chave de API (o backend o resolve internamente)
Todas as chaves usam o prefixo ps_.
Escopos de chave
| Escopo | Vinculada a | Onde encontrar |
|---|
| Escopo de número (padrão) | Um número de WhatsApp — todos os endpoints de ação/dados desse número (envio, status, grupos, templates, mídia, chamadas…) | Painel → página API Keys (uma chave padrão por número; Regenerar) |
| Escopo de tenant (singleton) | O tenant (sem número) — gerenciamento no nível da conta: /v1/numbers/*, /v1/remote-pairing/*, /v1/api-keys, /v1/branding, /v1/webhooks/*, /v1/subscription/*. Não pode enviar mensagens. | Painel → Perfil → aba API |
TENANT_SCOPE_NOT_ALLOWED; uma chave com escopo de número em um endpoint exclusivo de tenant recebe 403 NUMBER_SCOPE_NOT_ALLOWED.
GET /v1/api-keys — Listar chaves (somente escopo de tenant)
Uma chave com escopo de número recebe 403 NUMBER_SCOPE_NOT_ALLOWED. Retorna um array plano e enxuto — um item por número — com numberId, number, displayName, keyId, keyLast4, além do valor real utilizável (key, revealable: true). Chaves legadas retornam com key: null e revealable: false — regenere aquele número para obter um valor utilizável.
curl "https://pilotstatus.com.br/v1/api-keys" \
-H "x-api-key: ps_your_tenant_scoped_key"
[
{ "numberId": "wn_1", "number": "5511999999999", "displayName": "Suporte", "keyId": "k_aaa", "keyLast4": "wxyz", "key": "ps_4f1c...real...wxyz", "revealable": true },
{ "numberId": "wn_2", "number": "5511888888888", "displayName": "Vendas", "keyId": "k_bbb", "keyLast4": "abcd", "key": null, "revealable": false }
]
POST /v1/api-keys — Regenerar a chave de um número (somente escopo de tenant)
Envie o número alvo em whatsappNumberId: sua chave padrão anterior é rotacionada/invalidada e a nova key bruta é retornada uma única vez. Não há “criar outra chave” — cada número tem exatamente uma chave padrão. Número desconhecido → 404 NUMBER_NOT_FOUND.
curl -X POST "https://pilotstatus.com.br/v1/api-keys" \
-H "Content-Type: application/json" \
-H "x-api-key: ps_your_tenant_scoped_key" \
-d '{ "whatsappNumberId": "wn_1" }'
{
"numberId": "wn_1",
"keyId": "k_new",
"keyPrefix": "ps_",
"keyLast4": "wxyz",
"key": "ps_...newreal...",
"createdAt": "2026-06-28T15:00:00.000Z"
}
A regeneração rotaciona a única chave padrão do número escolhido — a chave anterior para de funcionar imediatamente. A chave bruta completa é exibida apenas uma vez na resposta: guarde-a agora.
POST /v1/api-keys/regenerate — Rotacionar a própria chave do chamador
Rotaciona a chave do próprio escopo da chave que faz a chamada (funciona para ambos os escopos): a chave atual é invalidada e a nova chave bruta é retornada uma única vez na resposta.
curl -X POST "https://pilotstatus.com.br/v1/api-keys/regenerate" \
-H "x-api-key: ps_current_key"
Privacidade e retenção de dados
A página de API Keys também hospeda o painel de Privacidade e retenção por número (o mesmo controle da página de Números). Ele determina se — e por quanto tempo — as conversas/o conteúdo das mensagens desse número são armazenados, e nunca afeta a entrega: o Chatwoot e os webhooks continuam funcionando em todos os modos (eles operam antes da camada de armazenamento). São três modos:
- Armazenar indefinidamente (
STORE_INDEFINITE, padrão) — mantém tudo para sempre.
- Armazenar por X dias (
STORE_X_DAYS) — mantém apenas os últimos N dias (piiRetentionDays, inteiro de 1 a 3650; uma tarefa diária apaga definitivamente os registros de chat mais antigos e redige o PII dos logs mais antigos).
- Não armazenar / apenas retransmitir (
RELAY_ONLY) — nunca persiste o chat; as mensagens ainda são retransmitidas (os webhooks disparam, o Chatwoot espelha), mas /chat e /logs ficam vazios e a mídia recebida não é re-hospedada.
Também é configurável via PATCH /api/whatsapp-numbers/{id} com { "piiMode": "STORE_X_DAYS", "piiRetentionDays": 30 }. Valores inválidos → 400 Invalid piiMode ou 400 piiRetentionDays must be an integer between 1 and 3650 para STORE_X_DAYS. Veja a página completa em Retenção de Dados.
Boas práticas de segurança
- Use as chaves de API somente no backend (nunca no navegador).
- Armazene as chaves em variáveis de ambiente / um gerenciador de segredos.
- Trate as respostas que contêm chaves brutas como sensíveis (não as registre em logs).
