Invalid Token: causas e soluções para o erro

Encontrar a mensagem “Invalid Token” ao tentar entrar em uma conta, utilizar um aplicativo, acessar uma API ou executar uma integração pode ser frustrante. O erro costuma aparecer de repente e nem sempre deixa claro o que realmente aconteceu.

Em português, “Invalid Token” significa “token inválido”. Na maioria dos casos, a mensagem indica que o sistema recebeu uma credencial digital que não consegue mais reconhecer ou aceitar. Isso pode acontecer porque o token expirou, foi revogado, está incompleto, foi enviado de maneira incorreta ou simplesmente não pertence ao serviço que está tentando validá-lo.

O problema é bastante comum em sites, aplicativos, APIs, sistemas empresariais e ferramentas utilizadas por desenvolvedores. Dependendo da situação, a solução pode ser tão simples quanto fazer login novamente. Em outros casos, será necessário revisar configurações de autenticação, cabeçalhos HTTP, permissões ou a geração do próprio token.

Neste artigo você vai entender o que significa Invalid Token, por que esse erro aparece e como resolver o problema em diferentes situações.

O que significa Invalid Token?

Invalid Token é uma mensagem de erro indicando que um token apresentado ao sistema não foi considerado válido para realizar determinada operação.

Um token funciona como uma espécie de credencial digital temporária. Ele pode ser utilizado para identificar uma sessão, comprovar uma autenticação ou autorizar determinado aplicativo a acessar um recurso.

Imagine que você entra em um sistema utilizando seu usuário e senha. Depois de confirmar que as informações estão corretas, o servidor pode gerar um token. Nas próximas solicitações, o sistema utiliza essa credencial para reconhecer que você já realizou a autenticação.

O processo simplificado pode funcionar assim:

1. o usuário informa suas credenciais;
2. o servidor verifica as informações;
3. uma credencial de acesso é gerada;
4. o aplicativo utiliza o token nas solicitações seguintes;
5. o servidor verifica se aquele token continua válido;
6. o acesso é permitido ou recusado.

Quando alguma coisa dá errado durante essa validação, mensagens como Invalid Token, Token Invalid, Invalid Access Token ou Authentication Token Invalid podem aparecer.

No padrão OAuth 2.0 para uso de Bearer Tokens, por exemplo, a RFC 6750 define invalid_token para situações nas quais o token fornecido está expirado, revogado, malformado ou inválido por outro motivo. Nesses casos, um servidor de recursos normalmente responde com o código HTTP 401 Unauthorized.

Apesar disso, a mensagem exata e o código apresentado podem variar conforme o sistema.

O que é um token e para que ele serve?

Antes de tentar resolver o erro Invalid Token, vale entender melhor o que é essa credencial.

Um token de autenticação ou autorização é uma sequência de dados utilizada por sistemas para representar determinadas informações e permissões.

Ele pode indicar, por exemplo:

• quem é o usuário;
• quando determinada credencial foi criada;
• quando ela deve expirar;
• quais recursos podem ser acessados;
• qual aplicação recebeu autorização;
• qual serviço emitiu o token;
• para qual sistema ele foi destinado.

Os tokens são muito utilizados porque evitam que usuário e senha precisem ser enviados novamente em todas as solicitações.

Existem diferentes tipos e formatos.

Entre os mais conhecidos estão os access tokens, utilizados para acessar recursos protegidos, e os refresh tokens, que podem ser empregados em determinados fluxos para obter novas credenciais de acesso.

Também existe o JWT, sigla para JSON Web Token, um formato padronizado que permite transportar informações entre partes por meio de uma estrutura própria.

Nem todo token é um JWT e nem todo sistema utiliza OAuth. Essa diferença é importante porque não existe uma solução universal para qualquer mensagem “Invalid Token”.

O procedimento correto depende de como o serviço implementou sua autenticação.

Principais causas do erro Invalid Token

Existem diversos motivos capazes de fazer um sistema rejeitar um token. Alguns são muito mais frequentes que outros.

1. Token expirado

A expiração está entre as causas mais comuns.

Por questões de segurança, muitos tokens possuem validade limitada. Depois desse período, o servidor deixa de aceitar a credencial mesmo que ela tenha funcionado normalmente alguns minutos ou horas antes.

No caso de um JWT, a claim exp, quando utilizada, determina o momento de expiração. A especificação RFC 7519 estabelece que o token não deve ser aceito a partir do horário indicado nessa informação.

Esse mecanismo reduz os riscos caso uma credencial seja comprometida.

Para um usuário comum, o problema pode acontecer quando uma página fica aberta durante muito tempo. A sessão expira e uma nova tentativa de realizar determinada ação encontra uma credencial antiga.

Nesse cenário, sair da conta e entrar novamente costuma gerar uma nova sessão.

Em uma API, o aplicativo pode precisar solicitar outro access token ou utilizar o mecanismo de renovação previsto pelo serviço.

2. Token digitado ou copiado incorretamente

Tokens podem ser sequências bastante extensas. Um único caractere faltando já pode fazer com que a credencial deixe de ser válida.

O problema é comum durante testes manuais em ferramentas de desenvolvimento.

Pode acontecer de:

• faltar uma parte do token;
• existir um espaço indevido;
• ocorrer uma quebra de linha;
• aspas serem incluídas por engano;
• caracteres serem removidos;
• uma variável de ambiente armazenar um valor antigo;
• o token errado ser copiado.

Por isso, quando a autenticação funcionava anteriormente e deixou de funcionar após uma alteração manual, conferir o valor utilizado é uma das primeiras verificações recomendadas.

3. Token revogado

Um token não precisa necessariamente chegar ao seu prazo de expiração para deixar de funcionar.

O servidor pode revogar determinada credencial antes disso.

Isso pode acontecer após:

• logout;
• alteração de senha;
• remoção de uma integração;
• mudança nas permissões;
• identificação de atividade suspeita;
• exclusão de uma sessão;
• alteração de configurações de segurança;
• revogação manual pelo administrador.

A RFC 6750 inclui tokens revogados entre as possíveis situações associadas ao erro invalid_token.

Se a credencial foi revogada, simplesmente tentar utilizar exatamente o mesmo token novamente provavelmente não resolverá o problema. Será necessário obter uma nova credencial conforme o processo de autenticação do serviço.

4. Token enviado no lugar errado

Outro problema frequente ocorre quando o token é válido, mas a aplicação o envia de maneira diferente daquela esperada pela API.

Muitas APIs que utilizam Bearer Tokens esperam receber a credencial no cabeçalho HTTP Authorization.

Um exemplo comum é:

Authorization: Bearer SEU_TOKEN

Se o desenvolvedor enviar apenas o valor do token sem o esquema esperado, utilizar outro cabeçalho ou montar a solicitação incorretamente, o servidor poderá recusar a autenticação.

Também é importante consultar a documentação específica da API. Diferentes serviços podem implementar autenticação de maneiras distintas.

5. Uso do token de um ambiente em outro

Sistemas profissionais frequentemente possuem ambientes separados.

É possível encontrar, por exemplo:

• desenvolvimento;
• teste;
• homologação;
• sandbox;
• produção.

Um token criado no ambiente de testes pode não funcionar no servidor de produção.

Imagine que uma aplicação possui:

api-teste.exemplo.com

e:

api.exemplo.com

Mesmo que as APIs sejam parecidas, suas credenciais podem ser completamente independentes.

Esse tipo de erro costuma confundir porque o token aparentemente está correto. Na realidade, ele apenas foi emitido para outro ambiente.

6. Token destinado a outro serviço

Tokens podem possuir informações indicando para quem determinada credencial foi emitida.

No JWT existe, por exemplo, a claim aud, de audience. Ela identifica os destinatários pretendidos para aquele token. A RFC 7519 estabelece que, quando essa claim está presente, o destinatário que processa o JWT precisa se identificar entre os valores previstos. Caso contrário, o token deve ser rejeitado.

Na prática, isso significa que não basta possuir qualquer token válido.

Ele precisa ser válido para aquele contexto.

Um token gerado para o Serviço A não necessariamente poderá ser utilizado no Serviço B.

7. Problemas com data e hora

Horários incorretos também podem causar problemas em determinadas implementações de autenticação.

Um JWT pode incluir informações temporais como:

• exp — momento de expiração;
• nbf — momento antes do qual o token não deve ser aceito;
• iat — momento em que o token foi emitido.

A própria RFC 7519 prevê uma pequena tolerância para diferenças de relógio em algumas dessas verificações.

Se servidores ou dispositivos estiverem com horários muito diferentes, uma credencial recém-criada pode parecer expirada ou ainda não válida.

Manter data, hora e fuso horário sincronizados é especialmente importante em servidores e ambientes distribuídos.

Como resolver o erro Invalid Token?

A solução depende de onde a mensagem está aparecendo.

Para facilitar, vale começar pelas alternativas mais simples antes de alterar configurações avançadas.

Se o erro apareceu em um site ou aplicativo

Usuários comuns podem tentar algumas ações básicas:

1. atualize a página;
2. feche e abra novamente o aplicativo;
3. saia da conta e faça login novamente;
4. verifique se o aplicativo está atualizado;
5. teste novamente depois de alguns minutos;
6. confira se a data e hora do dispositivo estão corretas;
7. se necessário, limpe os dados de sessão ou cache relacionados ao serviço;
8. redefina a senha caso o serviço solicite uma nova autenticação;
9. consulte a página de status ou suporte caso o problema continue.

Fazer logout e login novamente é especialmente útil quando a sessão expirou. O sistema normalmente realiza uma nova autenticação e pode emitir outra credencial.

Evite apagar dados importantes do aplicativo sem saber se eles estão sincronizados com a conta.

Se o erro acontece para vários usuários ao mesmo tempo, também existe a possibilidade de o problema estar no próprio serviço.

Como corrigir Invalid Token em uma API?

Quando o erro aparece durante o desenvolvimento ou integração com uma API, é necessário investigar um pouco mais.

Comece verificando o código HTTP retornado.

Um 401 Unauthorized normalmente aponta para problemas relacionados à autenticação. No padrão Bearer definido pela RFC 6750, um token expirado, revogado, malformado ou inválido deve resultar normalmente em HTTP 401.

Depois disso, verifique o cabeçalho de autenticação.

Uma requisição que utiliza Bearer Token costuma ter estrutura semelhante a:

Authorization: Bearer eyJ…

Confirme se existe um espaço entre Bearer e o token.

Depois verifique:

• o token ainda está dentro da validade?
• a credencial pertence ao ambiente correto?
• o endpoint está correto?
• o token possui as permissões necessárias?
• existe algum espaço ou quebra de linha no valor?
• a aplicação está enviando a credencial correta?
• uma variável de ambiente está desatualizada?
• o servidor revogou o token?
• a documentação exige algum cabeçalho adicional?

Também vale gerar uma nova credencial e repetir o teste.

Se o novo token funcionar imediatamente, existe uma forte indicação de que o problema estava relacionado ao ciclo de vida ou ao armazenamento da credencial anterior.

Confira se você está usando realmente um access token

Um erro relativamente comum entre iniciantes é confundir diferentes credenciais de autenticação.

Um sistema pode fornecer informações como:

• Client ID;
• Client Secret;
• API Key;
• Access Token;
• Refresh Token.

Elas não são necessariamente intercambiáveis.

Um Client Secret, por exemplo, não deve ser automaticamente tratado como Bearer Token apenas porque é uma sequência longa de caracteres.

A documentação do serviço deve indicar como cada credencial participa do processo de autenticação.

Invalid Token e JWT: como identificar o problema?

Quando a aplicação utiliza JWT, existem verificações adicionais que podem ajudar a localizar a falha.

Um JWT normalmente possui três partes separadas por pontos:

xxxxx.yyyyy.zzzzz

De maneira simplificada, elas representam cabeçalho, payload e assinatura.

O fato de conseguir visualizar o conteúdo do token não significa que ele seja automaticamente confiável.

O servidor precisa realizar as validações adequadas.

Entre os pontos que podem ser verificados estão:

• assinatura;
• algoritmo esperado;
• emissor;
• audiência;
• expiração;
• momento de validade;
• estrutura do token;
• chave utilizada na validação.

Um token pode ter uma estrutura aparentemente correta e mesmo assim ser rejeitado.

Por exemplo, imagine que o exp indique um horário que já passou. Nesse caso, a credencial não deve continuar sendo aceita após sua expiração conforme as regras aplicáveis.

Outro cenário envolve a audiência.

O token pode ter sido emitido corretamente e ainda estar dentro da validade. Mesmo assim, se foi destinado a outro serviço, o servidor atual poderá rejeitá-lo.

Invalid Token, Invalid Request e Insufficient Scope são iguais?

Não.

Essas mensagens podem parecer semelhantes porque todas podem aparecer durante o acesso a uma API protegida.

A RFC 6750 diferencia pelo menos três situações importantes:

invalid_request: a solicitação apresenta algum problema de formato ou parâmetro relacionado ao processo de autenticação.

invalid_token: o token está expirado, revogado, malformado ou é inválido por outro motivo.

insufficient_scope: a credencial existe, mas não possui privilégios suficientes para acessar determinado recurso.

Essa diferença é importante durante o diagnóstico.

Se o problema for Invalid Token, conseguir permissões adicionais para a mesma credencial pode não resolver nada.

Se o erro for Insufficient Scope, gerar outro token exatamente com as mesmas permissões também pode não adiantar.

O desenvolvedor precisa identificar o que o servidor realmente está recusando.

Erro Invalid Token pode ser problema de internet?

Normalmente, Invalid Token está mais relacionado à autenticação ou autorização do que à conexão com a internet.

Mesmo assim, problemas de conexão podem provocar comportamentos que confundem o usuário.

Imagine que um aplicativo tente renovar automaticamente uma credencial. A internet cai exatamente naquele momento e a renovação não acontece. Posteriormente, o programa continua tentando utilizar o token antigo.

Nesse cenário, a conexão contribuiu para o problema, mas a mensagem Invalid Token aparece porque a credencial utilizada já não é aceita.

Por isso, testar a conexão pode fazer parte do diagnóstico em aplicativos comuns, mas não deve ser tratado como a principal causa de todo erro desse tipo.

Como evitar que o erro Invalid Token volte a acontecer?

Em aplicações próprias, a prevenção depende de uma boa implementação do processo de autenticação.

Desenvolvedores devem evitar tratar tokens como valores permanentes.

Algumas boas práticas incluem:

• respeitar o tempo de validade da credencial;
• implementar corretamente o fluxo de renovação previsto pelo serviço;
• armazenar tokens de maneira segura;
• nunca registrar credenciais completas desnecessariamente em logs;
• não expor segredos no código-fonte;
• utilizar HTTPS;
• validar adequadamente tokens recebidos;
• separar credenciais de desenvolvimento e produção;
• tratar respostas HTTP 401;
• renovar credenciais quando o protocolo permitir;
• revogar tokens comprometidos;
• seguir a documentação oficial da API utilizada.

Bearer Tokens merecem atenção especial porque quem obtém uma credencial válida pode potencialmente utilizá-la dentro das permissões concedidas. A RFC 6750 destaca justamente a necessidade de proteger esses tokens contra divulgação e uso indevido.

Também é recomendável evitar colocar tokens reais em fóruns públicos, capturas de tela, repositórios de código ou mensagens abertas.

Caso uma credencial seja exposta acidentalmente, a atitude mais segura costuma ser revogá-la e gerar outra, seguindo os recursos disponibilizados pelo serviço.

Como descobrir rapidamente a causa do Invalid Token?

Quando o problema persiste, seguir uma sequência de diagnóstico evita perder tempo procurando causas aleatórias.

Primeiro, identifique onde o erro ocorre.

Se for um site ou aplicativo comum, tente renovar a sessão fazendo login novamente.

Se for uma API, observe a resposta completa do servidor sem expor informações confidenciais. O código HTTP e a descrição retornada podem revelar bastante sobre o problema.

Depois, confirme a validade da credencial e verifique se ela está sendo enviada exatamente como a documentação determina.

Em seguida, confira ambiente, endpoint, permissões e configurações.

Uma ordem prática de investigação pode ser:

Token existe → está completo → não expirou → não foi revogado → pertence ao ambiente correto → está sendo enviado corretamente → foi emitido para o recurso correto → possui as permissões necessárias.

Essa sequência cobre grande parte dos problemas encontrados no dia a dia.

Também é importante lembrar que Invalid Token não é o nome de um único erro universal. Diferentes sites e aplicativos podem utilizar a mesma expressão para situações distintas.

Quando uma plataforma específica apresenta essa mensagem, a documentação oficial daquele serviço deve ser a principal referência para descobrir exatamente o que ela significa.

Para usuários comuns, renovar a sessão costuma resolver boa parte dos casos. Para desenvolvedores, analisar validade, formato, cabeçalho, ambiente, audiência e processo de renovação geralmente revela onde está a falha.

Um token aparentemente complicado nada mais é do que uma peça do processo de autenticação. Depois que se entende onde ele é criado, como é enviado e quais regras determinam sua validade, o erro Invalid Token se torna muito mais fácil de diagnosticar.