​

Autenticação da API

• x-api-key: a chave bruta (ps_*)
• x-api-key-id: o ID da chave de API (o backend resolve internamente)

​

Prefixo da chave

​

Onde encontrar uma chave de API

• Chave com escopo de número: painel /api-keys — cada número de WhatsApp tem uma chave padrão que você pode Regenerar (não há subchaves / não há relação pai-filho).
• Chave com escopo de tenant: painel, aba Perfil → API — um singleton que você gera/regenera.

​

Escopo da chave (número vs. tenant)

​

Chave com escopo de número

​

Chave com escopo de tenant

• Ela gerencia números via /v1/numbers/* e /v1/remote-pairing/*, e gerencia recursos da conta: /v1/api-keys (listar a chave de cada número e regenerá-la), /v1/branding, /v1/subscription/extra-numbers, /v1/billing/checkout, /v1/webhooks/* e /v1/embed/sessions (connect).
• É o único escopo que pode gerenciar chaves de API por número via POST /v1/api-keys — uma chave com escopo de número não pode.
• Pode chamar qualquer endpoint por número — inclusive envio — indicando o número no cabeçalho x-whatsapp-number-id. Não é preciso uma chave separada por número.
• Ela é gerada/regenerada no painel, na aba Perfil → API.

​

Agir sobre um número específico com a chave de tenant

curl -X POST "https://pilotstatus.com.br/v1/messages/send" \
  -H "x-api-key: ps_sua_chave_de_tenant" \
  -H "x-whatsapp-number-id: <id de GET /v1/numbers>" \
  -H "Content-Type: application/json" \
  -d '{"destinationNumber":"5511999999999","text":"Oi"}'

{
  "error": "This endpoint acts on a single WhatsApp number: send the x-whatsapp-number-id header naming the number to act on (its id or instance id from GET /v1/numbers) | Este endpoint atua sobre um único número de WhatsApp: envie o header x-whatsapp-number-id indicando o número desejado (o id dele ou o id da instância, obtidos em GET /v1/numbers)",
  "code": "TENANT_SCOPE_NOT_ALLOWED"
}

​

Regenerar / rotacionar chaves

curl -X POST "https://pilotstatus.com.br/v1/api-keys/regenerate" \
  -H "x-api-key: ps_your_current_key"

​

Exemplos de requisições

curl "https://pilotstatus.com.br/v1/messages/msg_abc" \
  -H "x-api-key: ps_your_key_here"

curl "https://pilotstatus.com.br/v1/messages/msg_abc" \
  -H "x-api-key-id: ck_xxx"

​

Erros comuns

• 401 — cabeçalho x-api-key / x-api-key-id ausente ou inválido.
• 403 — chave válida, mas operação bloqueada (ex.: uma chave com escopo de tenant chamando um endpoint de ação por número → code: "TENANT_SCOPE_NOT_ALLOWED", ou uma chave com escopo de número chamando um endpoint exclusivo de tenant → code: "NUMBER_SCOPE_NOT_ALLOWED").

​

Boas práticas de segurança

• Armazene a chave em variáveis de ambiente / um gerenciador de segredos.
• Trate a resposta de criação/regeneração como sensível (não registre a chave completa em logs).