Sessão e tokens
O login devolve um access token (JWT de vida curta) e um refresh token. O SDK guarda os dois num TokenStore e cuida da renovação:
- Proativa: antes de cada request, se faltarem menos de 2 minutos para o access token expirar, o SDK renova primeiro.
- Reativa: se o gateway responder 401 por causa do token (um 401 sem código, como o middleware de autenticação do gateway responde a um token ausente, expirado ou inválido, ou um com
TOKEN_EXPIREDouTOKEN_STALE), o SDK renova e repete o request uma vez. Requests simultâneos compartilham um único refresh. Um 401 com qualquer outro código, comoINVALID_CREDENTIALSpara a senha atual errada emchangePasswordoudisable2fa, ouUNAUTHENTICATED/TOKEN_INVALIDrepassado de um serviço (ex.: um código de verificação errado), chega ao app como veio: sem refresh, sem repetição (a senha não é enviada duas vezes) e semonAccessTokenRejected. - Falha: se o refresh for recusado, a sessão é limpa e
onSessionExpiredé chamado. - Falha transitória: se o refresh cair por rede/timeout ou a resposta vier sem tokens válidos (
VALIDATION_ERROR), os tokens atuais são mantidos e o request falha com esse erro;onSessionExpirednão é chamado.
Clientes de servidor: autoRefresh: false
Clientes de servidor (RSC/SSR) devem usar autoRefresh: false; a renovação fica com o browser ou com um Route Handler.
const enginex = createEnginexClient({
baseUrl: 'https://gateway.operador.com',
tenantHost: 'casino.operador.com',
autoRefresh: false,
})Com autoRefresh: false, nem o refresh proativo (antes de um request, com o access token perto de expirar) nem o reativo (após um 401) chamam POST /auth/refresh:
- O access token guardado é usado como está.
- Um 401 chega ao chamador sem conserto:
auth: 'required'rejeita com o erro original do gateway;auth: 'optional'repete sem token — ou seja, uma chamadaoptionalcom o token expirado custa dois requests (o 401 e o retry sem token), em vez de um refresh. - A sessão local não é limpa e
onSessionExpirednão é chamado — o servidor não deve decidir isso por um cliente que não é dono da sessão.
Um cliente de servidor por request normalmente lê o access token de um cookie httpOnly (via tokenStore personalizado) e nunca precisa renová-lo: quem faz isso é o browser (com o cliente padrão, autoRefresh: true) ou um Route Handler dedicado.
Quando o app é o dono da sessão
Um app que já tem a própria autenticação (um store com login, refresh e logout) não quer que o SDK renove nem grave tokens: dois renovadores trocando o mesmo refresh token derrubam a sessão. Declare isso com sessionOwner: 'app':
import { createEnginexClient } from '@getenginex/sdk'
import { useAuthStore } from '@/stores/auth' // your store: login, logout and refresh belong to the app
import { authStoreTokens } from '@/lib/auth-tokens' // a TokenStore over the app's store
export const enginex = createEnginexClient({
sessionOwner: 'app',
tokenStore: authStoreTokens,
// The gateway refused the current access token: the app renews and writes the new tokens to the store.
onAccessTokenRejected: () => void useAuthStore.getState().refreshSession(),
})authStoreTokens é um TokenStore sobre o store do app: o exemplo está em Migrando um player Next.
Com 'app':
- O SDK só lê o
tokenStorepara assinar os requests e montarsession.get(). Nunca chamaPOST /auth/refreshe não limpa a sessão;onSessionExpirednão é chamado. auth.logineauth.logout(e qualquer escrita de sessão do SDK) rejeitam comCONFIGURATION_ERRORantes de enviar: login e logout são do app.- Um 401 chega ao chamador sem conserto (
auth: 'optional'ainda repete sem token). Quem renova é oonAccessTokenRejected. A exceção: se o app já gravou um token novo notokenStoreenquanto o request estava em voo, o SDK repete uma vez com o token novo (sem renovar nem gravar nada), e o 401 atrasado não chega ao chamador nem avisa o app. autoRefreshpassa a serfalse;autoRefresh: truejunto com'app'lançaCONFIGURATION_ERRORna criação do cliente. O mesmo vale paraonAccessTokenRejectedsemsessionOwner: 'app'(com'sdk', useonSessionExpired).
onAccessTokenRejected é chamado sem argumentos quando o gateway recusa (401 por causa do token, como acima) o access token atual:
- Uma vez por token. Uma rajada de 401 com o mesmo token (várias queries em paralelo) avisa uma vez só; um 401 atrasado de um token que já foi trocado no
tokenStorenão avisa (o request é repetido com o token novo). Se o token novo também for recusado, avisa de novo. - Dispara também em chamadas
auth: 'optional'(ex.:config.get), mesmo quando a repetição sem token dá certo. - Não dispara sem token (o
UNAUTHENTICATEDantes do envio) nem depois declient.dispose(). Uma exceção dentro dele não muda o erro da chamada. - O
unauthorizeddo realtime não dispara oonAccessTokenRejected: a conexão WebSocket avisa pelo próprio status (useRealtimeStatus), e a sessão continua sendo do app. Renove o token pelo mesmo caminho do app e a reconexão usa o token novo.
O hook onError continua sendo de observabilidade (um por chamada que falhar), não de renovação.
Onde guardar os tokens
| Store | Sobrevive a reload | Entre abas | Observação |
|---|---|---|---|
memoryTokenStore() (padrão) | não | não | Mais seguro contra XSS; o jogador loga de novo ao recarregar. |
localStorageTokenStore() | sim | sim | Legível por qualquer script da página: use com Content-Security-Policy. |
| Personalizado | depende | depende | Implemente TokenStore (get, set, clear, subscribe). |
O localStorageTokenStore sincroniza abas: se outra aba renovar os tokens, esta aba usa os novos em vez de gastar um refresh token já trocado.
Observando a sessão
enginex.session.get() // { status: 'authenticated', userId, operatorId, sessionId, expiresAt }
const off = enginex.session.subscribe((s) => console.log(s.status))session.get() devolve um objeto congelado com a mesma referência enquanto a sessão não muda (uma rotação só do refresh token não conta), e uma referência nova quando ela muda — dá para usar direto com useSyncExternalStore(enginex.session.subscribe, enginex.session.get) no React, sem loop de re-render.
createEnginexClient({ onSessionChange }) é um atalho para session.subscribe.
Callbacks do app (onSessionChange, onSessionExpired, onValidationIssue, listeners de subscribe e do TokenStore) nunca quebram uma operação do SDK: se um deles lançar, o login, o logout ou o request seguem normalmente e o erro é relançado numa microtarefa, então ainda aparece no console e no seu rastreador de erros.