Revogação de Token do Cliente (Admin)
Visão Geral
Este módulo permite que usuários administrativos encerrem todas as sessões de um cliente 🔒, revogando os tokens de autenticação emitidos para ele até o momento.
Use a revogação quando a sessão do cliente não deve mais valer: suspeita de fraude ou de acesso indevido, fim de uma sessão aberta por uma integração ou troca de dados sensíveis do cadastro.
Como a revogação funciona
- A revogação vale para todos os tokens do cliente emitidos até o momento da revogação (
createdAt). Não é possível revogar um token específico. - Tokens emitidos depois da revogação funcionam normalmente: o cliente pode entrar de novo assim que quiser.
- Revogar de novo um cliente que já tem revogação atualiza
createdAteexpiresAt, derrubando também os tokens emitidos entre as duas revogações. - A revogação dura o maior tempo de vida de um token emitido pela API (5 dias). Em
expiresAto registro é apagado automaticamente, porque nenhum token revogado pode mais estar válido. - A revogação vale só para a loja do usuário que fez a chamada.
- A revogação também derruba os tokens delegados do cliente (emitidos em
POST /customers/{customerId}/generate-token). Use-a para encerrar uma sessão delegada antes do vencimento dela. - CUSTOMER_READ: exigido por todas as rotas de clientes
- CUSTOMER_TOKEN_WRITE: necessário para revogar os tokens de um cliente
- customerId: ID do cliente que teve os tokens revogados
- createdAt: data e hora da revogação (
Y-m-d H:i:s). Todo token do cliente emitido até esse momento deixa de valer - expiresAt: data e hora em que a revogação é apagada automaticamente (
Y-m-d H:i:s), 5 dias depois decreatedAt
O que acontece com o token revogado
O token revogado tem o mesmo tratamento de um token vencido: o cliente deixa de estar autenticado.
| Onde o token é usado | Resultado |
|---|---|
Rotas do cliente logado (/customer/* que exigem login) | Erro REVOKED_AUTH_TOKEN (401). Para um token vencido, o erro é EXPIRED_AUTH_TOKEN (401) |
Carrinho (/cart/*) | A requisição segue com um carrinho novo, sem cliente vinculado, e a resposta traz um token novo sem o cliente |
| Rotas públicas (catálogo, cadastro, login etc.) | Funcionam normalmente, sem cliente autenticado |
Permissão
A revogação exige autenticação via middleware UserAuth e os escopos:
Estrutura da Revogação
O objeto retornado pela revogação contém as seguintes informações:
Revogação dos Tokens do Cliente
/customers/{customerId}/revoke-token
Endpoint responsável por revogar todos os tokens de autenticação emitidos para um cliente
Descrição
Este endpoint permite aos usuários administrativos encerrar todas as sessões de um cliente, revogando todos os tokens de autenticação emitidos para ele até o momento da chamada.
- Todos os tokens anteriores deixam de valer: nas rotas do cliente logado eles passam a receber o erro
REVOKED_AUTH_TOKEN(401), e no carrinho a requisição segue sem o cliente. - Tokens delegados do cliente (emitidos em
POST /customers/{customerId}/generate-token) também são revogados. - Novos logins depois da revogação funcionam normalmente.
- Revogar de novo atualiza a revogação existente, derrubando também os tokens emitidos depois da revogação anterior.
- A revogação é apagada automaticamente em
expiresAt(5 dias depois), quando nenhum token revogado pode mais estar válido.
Para entender o funcionamento completo, consulte a página Revogação de Token do Cliente.
Permissão
Requer os escopos CUSTOMER_READ e CUSTOMER_TOKEN_WRITE.
Parâmetros de Query
Headers Obrigatórios
| Header | Valor | Descrição |
|---|---|---|
Authorization | Bearer {userToken} | Token de autenticação do usuário |
Parâmetros de URL
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| customerId | integer | Sim | ID do cliente que terá os tokens revogados |
Exemplo de Requisição
1curl --request POST \2 --url '{{MAIN_URL}}/customers/123/revoke-token' \3 --header 'Authorization: Bearer SEU_TOKEN_AQUI'✅ Resposta de Sucesso
HTTP Status: 201 Created
1{2 "status": true,3 "data": {4 "customerId": 123,5 "createdAt": "2026-11-11 16:00:16",6 "expiresAt": "2026-11-16 16:00:16"7 }8}| Campo | Tipo | Descrição |
|---|---|---|
| customerId | integer | ID do cliente que teve os tokens revogados |
| createdAt | datetime | Momento da revogação (Y-m-d H:i:s). Todo token do cliente emitido até aqui deixa de valer |
| expiresAt | datetime | Momento em que a revogação é apagada automaticamente (Y-m-d H:i:s), 5 dias após createdAt |
⚠️ Possíveis erros:
Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.
Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.
| Código Interno | Código HTTP | Descrição |
|---|---|---|
| UAPPI_STORE_CUSTOMER_NOT_FOUND | 404 | O cliente não foi encontrado na loja, ou pertence a uma política comercial que o perfil do usuário não pode acessar |
| UAPPI_AUTH_FORBIDDEN_ACCESS | 403 | O perfil do usuário não tem os escopos CUSTOMER_READ e CUSTOMER_TOKEN_WRITE |
| USER_PROFILE_TRADE_POLICY_MISCONFIGURED | 422 | O perfil do usuário possui restrição de política comercial ativa, mas nenhuma política comercial permitida está configurada. |