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

Página de API Keys do Pilot Status — A página de API Keys — cada número tem uma chave padrão (exibida mascarada) com ação Regenerar, além de privacidade e retenção por número.

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

Não existem sub-chaves (sem pai/filho). No painel, as chaves são regeneradas, não criadas: cada número de WhatsApp tem uma chave padrão com escopo de número, e a chave com escopo de tenant é um singleton. Uma chave com escopo de tenant em um endpoint de ação por número recebe 403 TENANT_SCOPE_NOT_ALLOWED; uma chave com escopo de número em um endpoint exclusivo de tenant recebe 403 NUMBER_SCOPE_NOT_ALLOWED.

Chave de API com escopo de tenant em Perfil → API — A chave com escopo de tenant fica em Perfil → API — ela gerencia números via API pública e não envia mensagens.

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.

Um item por número — a chave criada mais recentemente. Um número pode ter mais de uma chave, e a listagem agora as reduz à mais nova em vez de devolver uma linha por chave. As chaves mais antigas não são revogadas: elas continuam autenticando, apenas deixam de aparecer na lista. Chaves sem número associado continuam sendo listadas individualmente.

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. Se o número tiver uma inbox nativa do Chatwoot e a chave nova não puder ser enviada para ela, as chaves anteriores são mantidas válidas de propósito para a inbox não quebrar — é assim que um número acaba com mais de uma chave funcionando. 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.

O modo é alterado no painel, na página API Keys (painel Privacidade & retenção) ou nas configurações do número em Números. 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).

Visão Geral

Mensagens

Modelos

Números

Conversas & Dados

Webhooks

Chamadas de Voz

Camada de Compatibilidade

Conta & Cobrança

Marca & Incorporação

Chaves de API — Listar, Regenerar, Rotacionar

Chaves de API — listar, regenerar, rotacionar

Escopos de chave

GET /v1/api-keys — Listar chaves (somente escopo de tenant)

POST /v1/api-keys — Regenerar a chave de um número (somente escopo de tenant)

POST /v1/api-keys/regenerate — Rotacionar a própria chave do chamador

Privacidade e retenção de dados

Boas práticas de segurança

​Chaves de API — listar, regenerar, rotacionar

​Escopos de chave

​GET /v1/api-keys — Listar chaves (somente escopo de tenant)

​POST /v1/api-keys — Regenerar a chave de um número (somente escopo de tenant)

​POST /v1/api-keys/regenerate — Rotacionar a própria chave do chamador

​Privacidade e retenção de dados

​Boas práticas de segurança

Chaves de API — listar, regenerar, rotacionar

Escopos de chave

GET /v1/api-keys — Listar chaves (somente escopo de tenant)

POST /v1/api-keys — Regenerar a chave de um número (somente escopo de tenant)

POST /v1/api-keys/regenerate — Rotacionar a própria chave do chamador

Privacidade e retenção de dados

Boas práticas de segurança