Visão geral
Como os tokens são assinados, como sua API verifica sem perguntar para nós, e o que o cliente está protegendo.
Duas coisas decidem se uma requisição é autêntica: a chave que assinou o access token e a chave que sua API usa para conferir. As duas são suas, e a segunda nunca precisa ser um segredo que você guarda.
Access token é assinado, não compartilhado
Todo access token que um ambiente emite é um JWT assinado com um par de chaves assimétrico. Seu ambiente guarda a metade privada; a pública é publicada, e é tudo que alguém precisa para verificar um token.
Não existe segredo de assinatura para copiar no seu backend, nem segredo para rotacionar entre serviços, nem nada que se transforme em vazamento quando um serviço expõe a configuração dele.
O formato segue a RFC 7519 para o token em si e a RFC 9068 para o uso como access token de OAuth 2.0 — então qualquer biblioteca JWT padrão verifica.
Verificando na sua própria API
Busque as chaves públicas no endpoint JWKS do ambiente e verifique a assinatura. O conjunto está em formato JWK, o mesmo servido por qualquer provedor OpenID:
https://<ambiente>.nulvless.co/auth/.well-known/jwks.jsonimport { createRemoteJWKSet, jwtVerify } from 'jose';
const keys = createRemoteJWKSet(
new URL('https://<ambiente>.nulvless.co/auth/.well-known/jwks.json'),
);
const { payload } = await jwtVerify(token, keys);O header do token traz um kid dizendo qual chave assinou, então a biblioteca
escolhe a certa dentro do conjunto sozinha. Deixe o conjunto em cache — a sua
biblioteca quase certamente já faz — e permita que ela busque de novo quando
encontrar um kid que não conhece.
Verificar a assinatura diz que o token é genuíno e não expirou. Não diz que o
usuário ainda tem as permissões que estão dentro dele, porque uma claim é um
retrato de quando o token foi emitido. Quando a pergunta é "ele pode fazer
isso", chame verify em vez de ler o JWT.
Refresh tokens
Um refresh token está ligado a uma sessão, e usá-lo o rotaciona: a resposta traz o próximo, e o que você enviou para de funcionar. Um refresh token que aparece de novo depois disso é tratado como vazamento, e a sessão é encerrada.
Existe uma exceção, e ela existe porque rede é instável. Uma repetição do token que você acabou de usar é tolerada por uma janela curta e respondida com um par novo, para que uma requisição repetida depois de um timeout não deslogue o usuário. O SDK de navegador cuida disso — ele compartilha uma renovação entre chamadas simultâneas e entre abas, então esse caso não deve surgir do seu próprio código.
É o comportamento de rotação com detecção de reuso recomendado para clientes públicos na RFC 9700, a boa prática de segurança do OAuth 2.0.
Não guarde um refresh token em lugar que uma página possa ler depois e repetir fora de ordem — uma segunda cópia no seu próprio estado é a forma usual de uma sessão ser encerrada por um vazamento que nunca houve. Deixe o SDK ser o dono dele.