Pular para o conteúdo principal

​
Tipos de chave de API

O Pilot Status tem três tipos de chave de API. Todas vão no mesmo cabeçalho x-api-key, e o prefixo diz de que tipo é a chave.
Chaves criadas antes de 28/10/2026 continuam funcionando. Elas têm o formato antigo ps_ + hex, sem o tipo no prefixo. Uma chave de número legada continua sendo uma chave de número, e uma chave com escopo de tenant legada continua sendo uma chave de workspace. Você não precisa trocá-las.

​
Chaves de número

Nada mudou aqui. Cada número de WhatsApp tem uma chave padrão, na página API Keys, que você regenera (não existe “criar outra”). Ela atua só no próprio número: uma chave de número em um endpoint exclusivo de workspace recebe 403 NUMBER_SCOPE_NOT_ALLOWED. Veja Chaves de API.

​
Chaves de workspace

Uma chave de workspace é o que a documentação chama de chave com escopo de tenant: ela é vinculada ao workspace, não a um número. Elas ficam numa tela própria, Chaves do workspace (/workspace-api-keys), na barra lateral. Antes de 28/10/2026 a chave do workspace ficava em Perfil → API; essa aba agora guarda as suas chaves de conta. Um workspace tem dois tipos de chave de workspace:
  • A chave bruta aparece uma única vez, quando é criada ou regenerada. Guarde-a na hora.
  • A sua chave com escopo de tenant atual é a chave principal do workspace.
  • Uma chave com nome criada por um membro é revogada quando esse membro sai do workspace.
  • Pela API, uma chave de conta lista, cria e revoga chaves de workspace com /v1/workspaces/{id}/api-keys, e rotaciona a chave principal com POST /v1/api-keys/regenerate.

​
Chaves de conta

Uma chave de conta é sua, não de um workspace. Qualquer usuário pode criar uma em Perfil → API, até 20 por usuário. Uma chave alcança todo workspace do qual você é membro ativo e, em cada requisição, atua com o seu papel atual no workspace indicado: se você for rebaixado ou removido, a chave perde esse acesso na próxima requisição. É a chave que um revendedor usa para criar um workspace por cliente final e operar todos eles com uma única credencial.

​
Escolha o workspace com x-workspace-id

Em todo endpoint que atua sobre um workspace, envie o id do workspace em x-workspace-id. Os ids vêm de GET /v1/workspaces.
  • Dentro desse workspace, a chave se comporta como a própria chave do workspace, limitada ao seu papel. Um papel que não permite a ação recebe 403 PERMISSION_DENIED.
  • Um membro restrito a alguns números alcança só esses números, como no painel.
  • x-whatsapp-number-id restringe a requisição a um número desse workspace, como numa chave de workspace. Um id que não é de um número desse workspace recebe 404 NUMBER_NOT_FOUND.
  • x-api-key-id não é aceito com chave de conta. Enviar os dois recebe 401 API key headers mismatch.
  • Chaves de conta carregam um usuário. Por isso elas fazem o que uma chave de workspace não faz, como gerenciar membros (conforme o seu papel), e podem criar chaves de workspace, o que tokens OAuth/MCP não podem.

​
Erros

Uma chave de conta é a credencial mais poderosa que você pode ter. Ela alcança todo workspace do qual você faz parte, com o seu papel em cada um. Mantenha-a só no seu servidor, nunca num navegador ou app, e revogue-a em Perfil → API se ela vazar.

​
Qual chave usar

  • Você envia mensagens por um número: uma chave de número.
  • Você opera um workspace e gerencia seus números, linhas e cobrança: uma chave de workspace — uma com nome por integração.
  • Você revende e mantém um workspace por cliente: uma chave de conta para criar os workspaces e atuar em cada um com x-workspace-id. Veja Cobrança para revendedores.