Como decodificar e inspecionar tokens JWT
JSON Web Tokens (JWTs) são a forma mais comum de lidar com autenticação em aplicações web modernas. Quando algo dá errado com autenticação — um usuário é deslogado inesperadamente, permissões estão erradas ou uma API retorna 401 — decodificar o JWT é geralmente o primeiro passo de depuração.
O que há dentro de um JWT
Um JWT tem três partes separadas por pontos: eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U
Cabeçalho — contém o algoritmo (HS256, RS256 etc.) e o tipo do token.
Payload — contém claims (afirmações de dados) sobre o usuário e o token.
Assinatura — um hash criptográfico que verifica que o token não foi adulterado. Você não pode lê-la sem a chave de assinatura.
Claims JWT comuns
sub (Subject) contém ID ou identificador do usuário. exp (Expiration) é o timestamp Unix de quando o token expira. iat (Issued At) é quando o token foi criado. iss (Issuer) indica quem criou o token (seu servidor de autenticação). aud (Audience) indica para quem o token se destina. nbf (Not Before) indica que o token não é válido antes desse momento. jti (JWT ID) é um identificador único para o token.
Como decodificar um JWT
1. Cole seu token — insira o JWT completo (formato cabeçalho.payload.assinatura) no decodificador. 2. Veja as seções decodificadas — a ferramenta exibe o cabeçalho (algoritmo), payload (claims) e assinatura como JSON formatado. 3. Verifique as claims — examine o tempo de expiração, emissor, sujeito e quaisquer claims personalizadas.
Depurando com JWTs
Token expirado? Verifique a claim exp. Converta o timestamp Unix para uma data legível. Se estiver no passado, o token expirou e precisa ser renovado.
Permissões erradas? Procure claims de função ou escopo no payload. Variam por implementação, mas frequentemente parecem com "role": "admin" ou "scope": "read write".
Problemas de identidade? A claim sub identifica o usuário. Verifique se corresponde ao ID esperado.
Token não aceito? Verifique a claim aud (audience). Se a API espera um valor específico de audience e o token tem outro, ele será rejeitado.
Notas importantes de segurança
- JWTs não são criptografados — qualquer um pode decodificar o payload. Não coloque senhas, chaves de API ou outros segredos em um JWT.
- Sempre verifique assinaturas no servidor — um decodificador mostra o que o token afirma, mas apenas a verificação da assinatura prova que ele não foi adulterado.
- Verifique a expiração — tokens expirados devem sempre ser rejeitados. Se seu app está aceitando tokens expirados, isso é um bug de segurança.
Perguntas frequentes
Posso verificar a assinatura de um JWT com um decodificador?
Não. A verificação de assinatura requer o segredo de assinatura ou chave pública, que fica no seu servidor. Um decodificador mostra o que há dentro do token, mas a verificação criptográfica deve acontecer no seu backend. Nunca confie em um JWT não verificado em produção.
É seguro colar um JWT em uma ferramenta online?
Sim, quando a ferramenta roda no seu navegador. Decodificadores baseados em navegador processam o token localmente — nada é enviado a um servidor. Evite ferramentas que fazem requisições de rede com seu token.
O que é a claim exp?
A claim exp (expiration) é um timestamp Unix indicando quando o token expira. Depois desse momento, o token deve ser rejeitado. Sempre verifique essa claim ao depurar problemas de autenticação.
JWTs podem ser criptografados?
JWTs padrão (JWS) são assinados mas não criptografados — qualquer um pode decodificar o payload. Tokens JWE (JSON Web Encryption) são criptografados, mas são menos comuns. Nunca coloque dados sensíveis (senhas, segredos) no payload de um JWT padrão.