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.
A Polymorfa tem credenciais distintas para a equipe e para projetos.
| Tipo | Prefixo | Autoridade |
|---|---|---|
| Chave da equipe | pmfa_… | Ações selecionadas em toda a equipe e em todos os projetos dela |
| Credencial do projeto | pmfa_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#
- Abra o projeto no Console.
- Abra Configurações → Chaves de API e escolha Criar chave do projeto.
- Escolha Você ou Conta de serviço, informe um rótulo e escolha uma validade.
- Selecione o menor conjunto de permissões de que a integração precisa.
- 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.
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 foundentre 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 foundcomo 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.