> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tokens de cliente

> Emita credenciais pmfa_ct_ de curta duração e aplique regras de sessão, destinatário, ação, origem e taxa.

Use um token de cliente de curta duração para fazer requisições a partir de um
navegador ou de um app de celular. Cada token fica limitado a uma sessão e às
ações que você permitir. Um [token por Customer](#tokens-por-customer), por sua
vez, cobre os números que um Customer possui.

## Emitir

Chame `POST /platform/client-tokens` com uma chave de projeto ou da equipe que tenha
todas estas permissões: `sessions:manage`, `messages:write`, `contacts:read`,
`presence:read`, `presence:observe` e `mcp`. Atualizar as regras da sessão exige as
mesmas permissões. Tokens emitidos com tetos de ação carregam um teto de ação
imutável. Cada requisição faz a interseção desse teto com as regras da sessão em
vigor e com a propriedade atual do número. Edições de regras não podem conceder
ações fora do teto.

Uma chave da equipe ou um token de projeto pertencente a uma pessoa só pode emitir
tokens enquanto essa pessoa continuar como proprietária ou administradora da
equipe e não estiver banida. Credenciais de conta de serviço não podem emitir
tokens que permitam ações de mensagens. O emissor precisa continuar ativo e não
revogado, com os escopos exigidos e a propriedade atual do número ou do Customer
selecionado. Essas verificações valem para toda emissão, incluindo renovações de
token.

Uma recusa por causa do emissor ou da propriedade atual retorna `403` sem token. Se
a Polymorfa não conseguir concluir as verificações de emissão, ela retorna `503`
sem token.

```json theme={null}
{
  "session": "739182640518203",
  "ephemeralId": "user_42",
  "ttlSeconds": 900
}
```

A resposta contém o token e a validade dele:

```json theme={null}
{
  "success": true,
  "data": {
    "token": "pmfa_ct_…",
    "expiresAt": "2030-01-01T00:15:00.000Z"
  }
}
```

`ttlSeconds` precisa estar dentro dos limites documentados para o endpoint. O token
fica restrito à equipe, à sessão, ao ID efêmero e à validade dele.

O `allow` de sessão exige inscrição no beta de tetos de ação. Até esse beta ser
ativado, requisições de sessão com `allow` são recusadas, e omitir o campo mantém o
formato de token baseado em regras que já existe. Tetos selados existentes
continuam sendo aplicados se a emissão de novos tetos for desativada.

`allow` também aceita um teto explícito para um token de sessão, incluindo as ações
`mcp` e `voip_*`. Um `allow` de sessão vazio não concede nenhuma ação da API. O `allow` de Customer precisa conter
pelo menos uma ação. Defina as regras antes de emitir. Um token sem ações
permitidas precisa ser emitido de novo depois que você configurar as regras dele.

Os nomes de ação `chats_read`, `chats_manage`, `contact_write` e
`contact_delete` são reservados para o acesso ao beta regional de equipes
inscritas. Incluir uma ação reservada não ativa Contatos ou Conversas regionais.
Tetos regionais também exigem o escopo de emissor correspondente: `chats:read`,
`chats:manage` ou `contacts:manage`. Essas permissões não autorizam rotas legadas
de conversas do WhatsApp. `read_contact`
continua cobrindo as consultas de contato documentadas; ela não concede acesso
irrestrito a um diretório de contatos retido. Tokens existentes não podem ganhar
essas ações reservadas por meio de uma edição de regra.

## Regras da sessão

As regras são gerenciadas separadamente:

```http theme={null}
GET    /platform/sessions/{session}/client-rules
PUT    /platform/sessions/{session}/client-rules
DELETE /platform/sessions/{session}/client-rules
```

```json theme={null}
{
  "recipientMode": "conversation",
  "allowedActions": "send_message,send_seen,send_typing",
  "rateLimit": 30,
  "maxDaily": 500,
  "allowedOrigins": "https://app.example.com",
  "conversationTtlSeconds": 86400,
  "enabled": true
}
```

`PUT` substitui o conjunto inteiro de regras. Campos opcionais omitidos voltam aos
valores padrão. As regras continuam valendo até que você as substitua ou exclua, e
excluir uma sessão também exclui as regras dela.

`recipientMode` é `conversation`, `any` ou `none`. Modos desconhecidos falham de
forma fechada (fail closed). `allowedActions` é uma lista separada por vírgulas que
contém apenas estes valores:

```text theme={null}
mcp                     send_message            send_reaction
send_typing             send_seen               read_presence
subscribe_presence      read_contact            voip_place
voip_answer             voip_signal
```

### Janela de conversa

No modo `conversation`, um token de cliente só pode enviar para um contato que tenha
mandado mensagem para a sessão dentro da janela de conversa. A janela recomeça a
cada nova mensagem desse contato.

`conversationTtlSeconds` define a janela, em segundos:

| Valor | Janela |
| - | - |
| `86400` (padrão) | 24 horas |
| `300` (mínimo) | 5 minutos |
| `604800` (máximo) | 7 dias |

Valores fora desse intervalo retornam `400`. Não existe janela sem expiração: um
contato que não manda mensagem para a sessão há mais de 7 dias precisa mandar uma
nova mensagem antes que um token de cliente possa responder.
As ações `voip_*` permitem chamadas. Três campos opcionais da regra limitam as
chamadas: `maxSetupsPerMinute` (inícios de chamada por minuto para cada
`ephemeralId`; `0` usa o padrão de 10), `allowedNumber` (uma lista separada por
vírgulas de números E.164 que o token pode chamar ou convidar) e `maxConcurrency`
(chamadas simultâneas; `0` significa sem limite). Consulte
[Chamadas](/pt-br/guides/calls/overview#authenticate-browser-clients).

Tokens de cliente nunca pareiam números. Use um [QuickLink](/pt-br/integrations/quicklink)
para conectar um número a partir de um navegador ou de um celular.

A ação `mcp` permite o handshake do protocolo. Cada ferramenta MCP continua
passando pelas regras normais de sessão, destinatário, ação, origem e taxa.

## Tokens por Customer

> [!NOTE]
>
> Os tokens por Customer estão em beta. Quando o beta for oferecido à sua equipe, um
> proprietário ou administrador da equipe seleciona **Participar** na linha do beta,
> na página **Números** de um projeto, e aceita os termos. Até a equipe participar,
> emitir com `customer` retorna `403`.

Quando um Customer possui vários números, emita um único token para o Customer em
vez de um por sessão. Passe o ID do Customer na Polymorfa em `customer` em vez de
`session`:

```json theme={null}
{
  "customer": "0190f0b6-7c1e-7a55-9d1a-2f0c6b1e4a10",
  "ephemeralId": "user_42",
  "allow": ["send_message", "read_presence"],
  "ttlSeconds": 900
}
```

* Envie exatamente um entre `session` e `customer`.
* `customer` é o ID do Customer na Polymorfa. Primeiro, procure o Customer pelo seu
  próprio ID externo no seu servidor; os tokens nunca aceitam um ID externo.
* A chave emissora também precisa de `customers:read`. Um token de projeto só pode
  emitir para Customers do próprio projeto. Uma chave da equipe pode emitir para
  qualquer Customer da equipe. Um Customer fora da equipe ou do projeto da chave
  retorna `404`.
* O Customer precisa estar ativo e possuir pelo menos um número, e o projeto
  precisa estar com Customers ativado. Um token cobre no máximo 64 números; emitir
  para um Customer com mais números retorna `400`.

O token cobre os números que o Customer possui no momento da emissão. Cada
requisição também é verificada em relação aos números atuais do Customer:

| Depois da emissão | Efeito no token |
| - | - |
| Um número passa para outro Customer | Requisições para esse número retornam `403` imediatamente. |
| Um número passa para este Customer | Não é coberto. Emita um novo token para incluí-lo. |
| O Customer é arquivado, ou Customers é desativado no projeto | Todas as requisições retornam `403`. |
| A equipe sai do beta | Todas as requisições retornam `403`. |

Chame as rotas de sessão normais com o ID de sessão do número no caminho, por
exemplo `POST /messaging/{session}/messages/send`. Cada requisição também precisa
passar pelas [regras](#regras-da-sessão) dessa sessão: um token por Customer nunca
permite mais do que as regras da sessão permitem.

`allow` restringe o token ainda mais. Ele aceita `send_message`,
`send_reaction`, `send_typing`, `send_seen`, `read_presence`,
`subscribe_presence` e `read_contact`. Para um Customer, omita o campo para usar
esse conjunto de ações original. Para uma sessão, a omissão registra as ações
configuradas no momento da emissão; sem regras, o token sai sem ações. Um token por Customer não pode usar chamadas (`voip_*`) nem MCP; emita um
token de sessão para isso.

## Comportamento de segurança

* Tokens de cliente não podem emitir outros tokens, incluindo tokens por Customer.
* Regras, estado de destinatário/conversa, restrições de origem e limites de taxa
  são verificados depois que o token é autenticado.
* Exclua ou desative as regras da sessão para interromper os efeitos permitidos
  antes que todos os tokens emitidos expirem.
* Cada alteração de regra aparece nos [Logs de auditoria](/pt-br/console/audit-logs) como
  `clientToken.rulesCreated`, `clientToken.rulesUpdated` ou
  `clientToken.rulesDeleted`. O registro informa quais campos mudaram, o modo de
  destinatário, os limites e a janela de conversa. Ele registra quantas origens e
  quantos números são permitidos, não as origens nem os números em si.
* Se um `PUT` ou `DELETE` retornar `503` com o código `service_unavailable`, a
  Polymorfa armazenou a alteração, mas não conseguiu confirmar que os tokens de
  cliente já a usam. Repita a mesma requisição depois do intervalo indicado em
  `Retry-After`.

## Indisponibilidade temporária

Os tokens de cliente falham de forma fechada. Se a Polymorfa não conseguir verificar
as regras de uma requisição, a requisição é recusada em vez de ser permitida sem
verificação:

* `503` com o código `credential_verification_unavailable` quando as regras da
  sessão não podem ser carregadas. O token continua válido; tente a requisição
  novamente.
* `503` com o código `service_unavailable` e um cabeçalho `Retry-After` quando um
  `rateLimit` por minuto ou a janela `conversation` não pode ser verificado. Tente
  novamente depois do número de segundos indicado.

Consulte [Emitir um token de cliente](/api-reference/platform/credentials/mint-client-token) e
[Regras da sessão](/api-reference/platform/credentials/get-client-rules) na referência da Platform API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.