Quando uma API retorna 401 Unauthorized para um JWT, tento eliminar causas em ordem em vez de trocar configurações aleatoriamente. Começo no header HTTP, depois tempo, assinatura, issuer, audience, tipo do token e só então permissões.
Se já tenho o token e conheço issuer ou audience esperados, começo no Depurador JWT.
1. Confirmo o Authorization header
Antes de investigar criptografia, olho a requisição:
Authorization: Bearer eyJ...
Procuro erros simples:
Bearerausente;- aspas extras;
- token em header errado;
- valor vazio ou truncado;
- espaços/quebras de linha copiados;
- variável errada no cliente;
- ID token ou refresh token no lugar do access token.
Um header malformado pode gerar 401 antes de qualquer validação JWT.
2. Decodifico sem confiar
Uso o Decodificador JWT e leio:
alg;kid;iss;aud;exp;nbf;- scopes e roles.
A decodificação cria hipóteses. Não prova autenticidade.
3. Verifico exp e nbf
Tempo é uma causa rápida de eliminar. Se exp está no passado, tenho uma explicação provável. Se nbf está no futuro, o token ainda não deveria ser aceito.
Uso o Verificador de Expiração JWT para converter NumericDate e enxergar clock skew.
Em bearer tokens OAuth, a RFC 6750 usa invalid_token para situações que podem incluir token expirado, revogado, malformado ou inválido de outra forma. Portanto, um 401 genérico não significa automaticamente expiração.
4. Verifico a assinatura com material confiável
Se o token está estruturalmente legível e dentro da janela de tempo, avanço para assinatura.
Pergunto:
- qual algoritmo a aplicação permite?
- qual issuer deveria ter assinado?
- qual secret/chave pública pertence a esse issuer?
kidcorresponde a uma chave confiável atual?
Falhas comuns incluem chave de ambiente errado, cache JWKS antigo, rotação, algoritmo incompatível e bytes do token modificados.
Uso o Verificador de Assinatura JWT ou, com JWKS, o Validador JWKS. Se falhar, sigo o guia de assinatura JWT inválida.
Nunca desativo a verificação para “sumir com o 401”.
5. Comparo o issuer
Depois de entender a assinatura, comparo iss com o issuer configurado.
Um caso clássico:
JWT iss: https://login.dev.example.com/
Esperado: https://login.example.com/
Isso aponta para ambiente ou trust domain errado. Também confirmo que a fonte JWKS usada pertence ao mesmo issuer.
O guia de validação de issuer JWT mostra essa cadeia completa.
6. Comparo a audience
Um token pode ter assinatura correta do issuer certo e ainda ser destinado a outra API.
API espera: api://orders
Token aud: api://billing
Nesse caso corrijo a solicitação do token ou a configuração da API, sem enfraquecer a validação.
Veja o fluxo de audience mismatch quando aud parece suspeito.
7. Confirmo o tipo de token
Uma integração pode funcionar no login e falhar na API porque o frontend enviou um ID token em vez do access token.
Pistas:
audaponta para o client ID;- scopes da API não aparecem;
- issuer parece correto, mas a API rejeita;
- o código anexou a variável errada ao Bearer header.
Confiro a documentação do provedor em vez de assumir que todo JWT serve para qualquer endpoint.
8. Separo 401 de problemas de autorização
Uso status code como pista:
- 401 normalmente aponta para credencial de autenticação não aceita;
- 403 normalmente aponta para identidade autenticada sem permissão suficiente.
A RFC 6750 diferencia invalid_token de insufficient_scope.
Frameworks variam, então, depois que autenticação passa, verifico scopes, roles e política do recurso.
9. Leio o erro específico no servidor
O cliente pode ver só 401, enquanto o servidor registra:
signature verification failed
issuer mismatch
audience mismatch
token expired
not yet valid
kid not found
insufficient scope
Esses logs são muito mais úteis depois que já eliminei hipóteses básicas.
Evito registrar o bearer token completo. Prefiro categoria do erro, issuer/audience esperados e kid, respeitando a política de segurança da aplicação.
Minha ordem completa para JWT 401
- Confirmo
Authorization: Bearer. - Decodifico o JWT e leio header/claims.
- Verifico
exp,nbfe relógio. - Verifico assinatura com chave confiável.
- Comparo
iss. - Comparo
aud. - Confirmo o tipo correto de token.
- Inspeciono scopes, roles e permissões.
- Leio o erro detalhado do servidor.
- Corrijo a etapa que falhou sem desabilitar validação.
A lição mais útil desse fluxo é que um JWT pode decodificar perfeitamente e ainda falhar em todas as verificações que realmente importam para autenticação. Resolver o 401 significa descobrir qual regra o resource server está aplicando e por que o token apresentado não satisfaz essa regra.
