Fluxo de depuração de JWT

Quando uma API retorna 401 Unauthorized ou 403 Forbidden, decodificar o JWT pode estreitar o problema rapidamente.

Comece pela forma

Confirme que o token tem três segmentos e não foi truncado por cópia, proxy, limite de header ou quebra de linha.

Inspecione claims de tempo

Cheque exp, nbf e iat.

• Se exp está no passado, peça um token novo.
• Se nbf está no futuro, procure skew de relógio ou horário errado do ambiente.
• Se iat surpreende, confirme se o cliente usa o emissor esperado.

Cheque issuer e audience

Compare iss e aud com a API que você chama. Um bug OAuth comum é usar ID token onde se exige access token.

Cheque escopos e papéis

Se autenticação passa mas autorização falha, inspecione scope, scp, roles, permissions ou campos equivalentes do seu provedor.

Verifique no sistema real

Depois que o decode apontar a direção certa, reproduza a requisição pelo verificador real do backend. O decodificador explica o token; o verificador decide se ele é aceito.

Resumo

Use decode para hipóteses rápidas; use verify para a decisão final. Documente o checklist (forma → tempo → iss/aud → escopos → backend) para incidentes repetíveis.

Cole o token no Decodificador JWT para ver header, payload e status de exp/nbf/iat antes de alterar configuração do servidor.