Ciclo de vida do token na prática

Todo guia de fluxo OAuth menciona refresh_token, mas uma integração de longa duração (que continua rodando ao longo de muitas requisições, workers ou dias) precisa de mais do que “trocar o token quando ele expirar”. Esta página cobre a duração real dos tokens, como armazenar um token em cache entre workers, quando renová-lo e o que pode invalidar um token antes que ele expiraria naturalmente.

---

Duração dos tokens por fluxo

A duração do token de acesso é um único período fixo, igual para todos os fluxos. A do token de atualização não é: depende de qual fluxo OAuth o emitiu.

Fluxo	TTL do token de acesso	TTL do token de atualização
Fluxo Client Credentials	Cerca de 1 hora	Cerca de 30 dias
Fluxo de Aplicativo Nativo (PKCE, redirecionamento loopback)	Cerca de 1 hora	Sem expiração fixa: permanece válido até ser substituído por rotação ou revogado
Fluxo Authorization Code + Redirecionamento Personalizado	Cerca de 1 hora	Sem expiração fixa: permanece válido até ser substituído por rotação ou revogado

Nota

Ambos os fluxos Authorization Code emitem um token de atualização sem nenhum relógio de sessão. Ainda assim, ele não fica indefinidamente sem uso: é um token de uso único, substituído a cada renovação (veja Condições de corrida em renovações simultâneas abaixo), e para de funcionar imediatamente se a concessão for revogada.

Armazene o token em cache, não gere um por requisição

Solicitar um novo token de acesso a cada chamada de API, ou de forma independente em cada processo worker, funciona, mas desperdiça uma ida e volta em cada requisição para um token que já é válido por cerca de uma hora. Solicite um token, armazene-o em cache (em memória para um único processo, ou em um armazenamento compartilhado como o Redis para uma frota de workers) pela credencial que o emitiu, e forneça o token em cache para cada requisição até que ele esteja próximo de expirar.

Isso também importa para o token de atualização: quanto menos processos o trocarem de forma independente, menor a chance de você esbarrar na condição de corrida descrita abaixo.

Renove ao expirar, não apenas em um 401

Como a TTL do token de acesso é fixa e conhecida com antecedência, renove de forma proativa: acompanhe quando você obteve o token (ou decodifique seu claim exp) e solicite um novo pouco antes desse momento, em vez de esperar uma requisição falhar primeiro.

Ainda assim, trate uma requisição que falhou como um recurso alternativo, mas diferencie de acordo com o erro recebido:

• 401 com not_authenticated: a requisição não trazia nenhum token portador utilizável. Isso é um bug do lado do cliente (cabeçalho Authorization ausente ou malformado), não um sinal para renovar.
• 401 com invalid_token: a verificação de assinatura ou expiração do token falhou. Renove e tente novamente uma vez.
• 403: nunca é um problema de token. O token é válido; quem chamou não tem o escopo, o acesso ao conteúdo ou o papel que a operação exige. Renovar não vai ajudar. Veja Códigos de erro: Limite de taxa, autenticação e controle de acesso para o detalhamento completo de cada código.

Condições de corrida em renovações simultâneas

Um token de atualização é de uso único: trocá-lo com grant_type=refresh_token invalida esse token de atualização e emite juntos um novo token de acesso e um novo token de atualização. Se vários workers compartilham um mesmo token de atualização em cache e dois deles tentam renovar quase ao mesmo tempo, apenas uma das trocas é bem-sucedida; a outra recebe um 401 genérico, não um erro distinto de “já utilizado”.

Cuidado

Não deixe cada worker renovar de forma independente contra um token de atualização compartilhado. Designe um único responsável pela chamada de renovação (um lock em torno do caminho de renovação, ou uma rotina dedicada) e faça os demais workers lerem o token de acesso resultante do cache compartilhado, em vez de renovarem por conta própria.

O que invalida um token antecipadamente

Nenhum dos eventos abaixo revoga diretamente um token de acesso ainda válido. Cada um bloqueia apenas algo novo (uma nova solicitação de token, ou a próxima renovação) enquanto o token de acesso já em mãos continua funcionando até que sua própria TTL se esgote.

Gatilho	Efeito
O segredo de cliente do aplicativo OAuth é rotacionado	Novas solicitações de token ou renovação usando o segredo antigo são rejeitadas imediatamente. Um token de acesso já emitido não é afetado e continua funcionando até expirar naturalmente.
O aplicativo OAuth ou seu usuário de serviço é removido	Bloqueia a emissão de novos tokens para esse aplicativo. Tokens já emitidos não são revogados de forma proativa.
Os escopos do aplicativo OAuth são alterados	Um token de acesso já emitido mantém seus escopos originais pelo resto de sua vida útil. O token só passa a usar os novos escopos na próxima renovação ou reemissão.
A concessão é explicitamente revogada	Bloqueia imediatamente a próxima tentativa de renovação. O token de acesso ainda válido não é expirado à força e continua funcionando até expirar naturalmente.

Nota

A janela de exposição prática após qualquer um desses eventos é a própria TTL do token de acesso (cerca de uma hora), não a do token de atualização, já que nenhum deles afeta um token já emitido. Para reduzir essa janela a zero imediatamente, revogue a concessão e rotacione o segredo juntos, e depois trate a integração como não autorizada até que uma TTL de token de acesso tenha decorrido.

Próximos passos

• Códigos de erro para o detalhamento completo das respostas 401 e 403
• Fluxo Client Credentials, Fluxo de Aplicativo Nativo ou Fluxo Authorization Code + Redirecionamento Personalizado para obter seu primeiro token