Sesión y tokens
El inicio de sesión devuelve un access token (un JWT de vida corta) y un refresh token. El SDK guarda ambos en un TokenStore y se encarga de la renovación:
- Proactiva: antes de cada request, si faltan menos de 2 minutos para que expire el access token, el SDK renueva primero.
- Reactiva: si el gateway responde 401 por el token (un 401 sin código, como responde el middleware de autenticación del gateway a un token ausente, expirado o inválido, o uno con
TOKEN_EXPIREDoTOKEN_STALE), el SDK renueva y repite el request una vez. Los requests simultáneos comparten un único refresh. Un 401 con cualquier otro código, comoINVALID_CREDENTIALSpor la contraseña actual incorrecta enchangePasswordodisable2fa, oUNAUTHENTICATED/TOKEN_INVALIDreenviado desde un servicio (p. ej., un código de verificación incorrecto), llega a la app tal cual: sin refresh, sin repetición (la contraseña no se envía dos veces) y sinonAccessTokenRejected. - Falla: si se rechaza el refresh, la sesión se limpia y se llama a
onSessionExpired. - Falla transitoria: si el refresh falla por red/timeout o la respuesta llega sin tokens válidos (
VALIDATION_ERROR), se mantienen los tokens actuales y el request falla con ese error; no se llama aonSessionExpired.
Clientes de servidor: autoRefresh: false
Los clientes de servidor (RSC/SSR) deben usar autoRefresh: false; la renovación queda a cargo del browser o de un Route Handler.
const enginex = createEnginexClient({
baseUrl: 'https://gateway.operador.com',
tenantHost: 'casino.operador.com',
autoRefresh: false,
})Con autoRefresh: false, ni el refresh proactivo (antes de un request, con el access token por expirar) ni el reactivo (tras un 401) llaman a POST /auth/refresh:
- El access token guardado se usa tal cual.
- Un 401 llega a quien llama sin reparar:
auth: 'required'rechaza con el error original del gateway;auth: 'optional'repite sin token — es decir, una llamadaoptionalcon el token expirado cuesta dos requests (el 401 y el retry sin token), en lugar de un refresh. - La sesión local no se limpia y no se llama a
onSessionExpired— el servidor no debe decidir eso a través de un cliente que no es dueño de la sesión.
Un cliente de servidor por request normalmente lee el access token de una cookie httpOnly (vía un tokenStore personalizado) y nunca necesita renovarlo: eso lo hace el browser (con el cliente por defecto, autoRefresh: true) o un Route Handler dedicado.
Cuando la app es dueña de la sesión
Una app que ya tiene su propia autenticación (un store con inicio de sesión, refresh y cierre de sesión) no quiere que el SDK renueve ni escriba tokens: dos renovadores intercambiando el mismo refresh token tumban la sesión. Decláralo con 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 es un TokenStore sobre el store de la app: el ejemplo está en Migrando un player Next.
Con 'app':
- El SDK solo lee el
tokenStorepara firmar los requests y armarsession.get(). Nunca llama aPOST /auth/refreshy no limpia la sesión; no se llama aonSessionExpired. auth.loginyauth.logout(y cualquier escritura de sesión del SDK) rechazan conCONFIGURATION_ERRORantes de enviar: el inicio y el cierre de sesión son de la app.- Un 401 llega a quien llama sin reparar (
auth: 'optional'aún repite sin token). Quien renueva esonAccessTokenRejected. La excepción: si la app ya escribió un token nuevo en eltokenStoremientras el request estaba en vuelo, el SDK repite una vez con el token nuevo (sin renovar ni escribir nada), y el 401 atrasado no llega a quien llama ni avisa a la app. autoRefreshpasa a serfalse;autoRefresh: truejunto con'app'lanzaCONFIGURATION_ERRORal crear el cliente. Lo mismo aplica aonAccessTokenRejectedsinsessionOwner: 'app'(con'sdk', usaonSessionExpired).
onAccessTokenRejected se llama sin argumentos cuando el gateway rechaza (401 por el token, como arriba) el access token actual:
- Una vez por token. Una ráfaga de 401 con el mismo token (varias queries en paralelo) avisa una sola vez; un 401 atrasado de un token que ya fue reemplazado en el
tokenStoreno avisa (el request se repite con el token nuevo). Si el token nuevo también es rechazado, avisa de nuevo. - También se dispara en llamadas
auth: 'optional'(p. ej.,config.get), incluso cuando la repetición sin token sale bien. - No se dispara sin token (el
UNAUTHENTICATEDantes del envío) ni después declient.dispose(). Una excepción dentro de él no cambia el error de la llamada. - El
unauthorizeddel realtime no disparaonAccessTokenRejected: la conexión WebSocket avisa por su propio estado (useRealtimeStatus), y la sesión sigue siendo de la app. Renueva el token por el mismo camino de la app y la reconexión usa el token nuevo.
El hook onError sigue siendo de observabilidad (uno por llamada que falle), no de renovación.
Dónde guardar los tokens
| Store | Sobrevive al reload | Entre pestañas | Observación |
|---|---|---|---|
memoryTokenStore() (por defecto) | no | no | Más seguro contra XSS; el jugador inicia sesión de nuevo al recargar. |
localStorageTokenStore() | sí | sí | Legible por cualquier script de la página: úsalo con una Content-Security-Policy. |
| Personalizado | depende | depende | Implementa TokenStore (get, set, clear, subscribe). |
localStorageTokenStore sincroniza las pestañas: si otra pestaña renueva los tokens, esta pestaña usa los nuevos en lugar de gastar un refresh token ya intercambiado.
Observando la sesión
enginex.session.get() // { status: 'authenticated', userId, operatorId, sessionId, expiresAt }
const off = enginex.session.subscribe((s) => console.log(s.status))session.get() devuelve un objeto congelado con la misma referencia mientras la sesión no cambia (una rotación solo del refresh token no cuenta), y una referencia nueva cuando cambia — se puede usar directamente con useSyncExternalStore(enginex.session.subscribe, enginex.session.get) en React, sin bucle de re-render.
createEnginexClient({ onSessionChange }) es un atajo para session.subscribe.
Los callbacks de la app (onSessionChange, onSessionExpired, onValidationIssue, listeners de subscribe y del TokenStore) nunca rompen una operación del SDK: si uno de ellos lanza, el inicio de sesión, el cierre de sesión o el request siguen normalmente y el error se relanza en una microtarea, así que todavía aparece en la consola y en tu rastreador de errores.