Pular para o conteúdo
Atalho: /, ⌘K ou Ctrl+K

Chaves de API e credenciais de projeto

Emita e revogue chaves da equipe e credenciais pmfa_pt_ com escopo de projeto sem cruzar limites de autoridade.

Ver em Markdown

A Polymorfa tem credenciais distintas para a equipe e para projetos.

TipoPrefixoAutoridade
Chave da equipepmfa_…Ações selecionadas em toda a equipe e em todos os projetos dela
Credencial do projetopmfa_pt_…As mesmas capacidades de máquina dentro de um projeto, mais um conjunto explícito de escopos de ação

O token completo é retornado uma única vez. Guarde-o com segurança quando ele for criado; o Console não consegue mostrá-lo de novo.

Uma credencial recém-criada aparece completa na caixa de diálogo de salvamento. Selecione Copiar e guarde-a com segurança. Somente Concluir fecha a caixa de diálogo. Trocar de projeto oculta imediatamente a credencial do projeto anterior.

Propriedade#

As chaves da equipe e as chaves de projeto oferecem a propriedade Você ou Conta de serviço, com permissões configuráveis.

  • Você cria uma chave pessoal. Suas chaves pessoais são revogadas quando você é removido da equipe, rebaixado para uma função abaixo de proprietário ou administrador, banido ou quando a sua conta é excluída. Restaurar o acesso não restaura as chaves revogadas.
  • Conta de serviço cria uma identidade com nome para a integração. A chave dela continua válida quando a pessoa que a criou muda. Revogue a chave quando a integração não precisar mais de acesso.

As chaves existentes mantêm o acesso como chaves de conta de serviço. A propriedade não amplia as permissões selecionadas nem o escopo de equipe/projeto da chave. As revogações automáticas de chaves pessoais entram em vigor à medida que as atualizações de revogação chegam às conexões ativas.

Controles de cobrança#

As chaves da equipe precisam de billing:read para ler limites de gastos e prioridades de financiamento, e de billing:manage para alterá-los. Essas permissões são exclusivas da equipe. Credenciais de projeto e tokens de cliente não podem usá-las. Chaves existentes não ganham novas permissões de cobrança automaticamente.

Consulte Uso para ver os controles e as verificações de revisão usadas pela API.

Logs de requisições#

Chaves da equipe e credenciais de projeto precisam de logs:read para ler o log de requisições. Selecione Logs de requisições → Leitura ao criar a chave. Chaves existentes, incluindo chaves criadas com todas as permissões, não ganham essa permissão automaticamente.

A chave de teste do projeto também pode listar os logs de requisições e os eventos do projeto e ler um evento. Ela vê apenas as linhas de números de teste do próprio projeto. Uma chave de teste criada antes desse acesso não tem events:read e logs:read; gere uma nova chave para adicioná-los.

Criar uma credencial de projeto#

  1. Abra o projeto no Console.
  2. Abra Configurações → Chaves de API e escolha Criar chave do projeto.
  3. Escolha Você ou Conta de serviço, informe um rótulo e escolha uma validade.
  4. Selecione o menor conjunto de permissões de que a integração precisa.
  5. Crie a credencial e copie o token completo imediatamente.

Escolha as permissões Todas, Restritas ou Somente leitura. Em cada linha de recurso, Nenhuma não concede acesso, Leitura concede as ações de leitura disponíveis e Escrita concede acesso de leitura mais as ações de escrita ou de gerenciamento do recurso. Cada linha oferece apenas os níveis de acesso compatíveis com aquele recurso. Selecione Webhooks → Leitura para inspecionar endpoints ou Webhooks → Escrita para gerenciá-los. A inspeção de entregas e as novas tentativas têm a própria linha, Entregas de webhook.

Emitir tokens de navegador e atualizar as regras de sessão deles exige, em conjunto, as permissões de escrita de sessões, escrita de mensagens, leitura de contatos, leitura/observação de presença e MCP. Consulte delegação com tokens de cliente.

As credenciais de projeto exigem pelo menos um escopo seguro para projetos. Consulte Autenticação para ver a lista de escopos. Selecionar * concede todas as ações seguras para projetos disponíveis para a sua equipe no momento em que a credencial é emitida. Isso não concede acesso aos membros da equipe, à cobrança ou às configurações da equipe, à administração de chaves de API da equipe nem a operações exclusivas do painel.

Somente uma pessoa conectada ao Console pode criar, listar ou revogar chaves da equipe e tokens de projeto. Chaves de API e tokens de projeto não podem gerenciar nenhum dos dois tipos de credencial. A API pública oferece endpoints de credenciais apenas para tokens de cliente.

Revisar e revogar#

O Console lista o prefixo, os últimos quatro caracteres, o rótulo, os escopos, a validade, a data de criação, o último uso e a data de revogação de cada credencial. Ele nunca mostra o token completo de novo.

Para revogar, abra o menu da linha da credencial, selecione Revogar e confirme na caixa de diálogo que mostra o nome dela. Em uma rotação planejada, confirme que a integração já passou a usar a credencial substituta antes de revogar a antiga.

Chaves da equipe#

Abra a equipe sem selecionar um projeto, depois abra Configurações → Chaves da equipe e escolha Criar chave da equipe. A Platform API pública não oferece operações de gerenciamento de chaves ou tokens. Escolha a propriedade e as permissões da mesma forma que para uma chave de projeto. As ações selecionadas valem para toda a equipe e para todos os projetos dela. Operações de conta exclusivas de pessoas continuam exigindo um usuário conectado ao painel. Conexões brutas com a bridge do WhatsApp exigem uma chave de projeto com bridge:connect; elas não aceitam chaves da equipe.

Usar com a Graph API#

A Graph API aceita as mesmas chaves da equipe e tokens de projeto no lugar de um token de acesso da Meta e recusa tokens de cliente e chaves de teste. O método debug_token descreve a chave no formato da Meta, com as permissões do WhatsApp convertidas para os nomes de escopo da Meta.

Graph API
curl "https://api.polymorfa.com/graph/whatsapp/v26.0/debug_token" \
  -H "Authorization: Bearer $POLYMORFA_KEY"

Regras de segurança#

  • Use uma credencial de projeto para cargas de trabalho que só precisam de um projeto.
  • Trate um 404 resource not found entre projetos como uma falha de limite; não tente novamente com o identificador de outro projeto.
  • Nunca use um token de cliente para emitir outra credencial.
  • Para fazer a rotação, faça o deploy da nova credencial antes de revogar a antiga.
  • Trate 404 credential not found como uma credencial ausente ou inacessível. Não use identificadores de outra equipe ou de outro projeto.

Notificações de primeiro uso#

Ative Primeiro uso de chave de API em Minhas notificações para receber um e-mail quando uma chave da equipe ou de projeto recém-emitida passar pela verificação de credenciais pela primeira vez. Esse alerta não confirma que a requisição foi concluída com sucesso. Ele não registra retroativamente o primeiro uso de chaves emitidas antes da criação do alerta.

Os e-mails de segurança de primeiro uso identificam a credencial da equipe ou do projeto e mostram o cliente informado pela requisição, o IP e a localização aproximada quando disponíveis, e o horário. Eles incluem os links Configurações da conta e Gerenciar sessões. Esse contexto identifica o uso de rede de uma credencial; ele não identifica um operador humano. Detalhes da requisição indisponíveis aparecem como Indisponível. Consulte Configurações de notificações pessoais para escolher a entrega por e-mail do primeiro uso de chaves de API.