# 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](https://docs.polymorfa.com/pt-br/billing/usage#prioridade-de-financiamento) 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](https://docs.polymorfa.com/development/request-logs). 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](https://docs.polymorfa.com/testing/test-key) 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](https://docs.polymorfa.com/pt-br/development/client-tokens).

As credenciais de projeto exigem pelo menos um escopo seguro para projetos. Consulte
[Autenticação](https://docs.polymorfa.com/api/authentication#permissions) 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](https://docs.polymorfa.com/api/client-tokens/mint-client-token).

## 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](https://docs.polymorfa.com/api/graph) 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`](https://docs.polymorfa.com/api/graph/credentials/inspect-an-access-token) descreve a
chave no formato da Meta, com as permissões do WhatsApp convertidas para os nomes
de escopo da Meta.

```bash 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](https://docs.polymorfa.com/pt-br/teams#personal-notification-settings)
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](https://docs.polymorfa.com/pt-br/teams#personal-notification-settings)
para escolher a entrega por e-mail do primeiro uso de chaves de API.
