Session Strategies
Configure how Aura Auth stores and maintains user sessions across requests.
The session option on createAuth defines the session management strategy — how a user's session is stored and validated on subsequent requests. Aura Auth currently supports the jwt (stateless) strategy.
import { createAuth } from "@aura-stack/auth"
export const auth = createAuth({
oauth: [],
session: {
strategy: "jwt",
maxAge: 60 * 60 * 24 * 7, // 7 days in seconds
jwt: {
mode: "sealed",
},
},
})jwt strategy
The jwt session strategy is the stateless option: it uses a JSON Web Token to represent the session, with no server-side storage or database lookup required to validate a request.
Options
| Option | Type | Required | Description |
|---|---|---|---|
mode | "sealed" | "signed" | "encrypted" | No (default "sealed") | Determines how the JWT is protected. See Choosing a mode below. |
issuer | string | No | Sets the iss claim on the JWT, identifying the issuer of the token. Useful for additional validation on the client or server. |
audience | string | No | Sets the aud claim on the JWT, identifying the intended audience. Useful for restricting token usage to specific clients or services. |
maxAge | number (seconds) | Yes | |
maxExpiration | number (seconds) | No | |
expirationStrategy | "absolute" | "rolling" | "fixed" | "sliding" | No (default "absolute") | absolute expires the token a fixed time after issuance. rolling extends the expiration on each request, keeping active users signed in. |
Choosing a mode
sealed(default) — encrypts the token, providing both confidentiality and integrity. The payload is not readable without the secret, and it cannot be tampered with. Use this unless you have a specific reason not to.signed— signs the token without encrypting it. Integrity is guaranteed (the token cannot be modified undetected), but the payload is plainly visible to anyone holding the token. Use this only if you need the payload to be readable outside of Aura Auth (for example, by a separate service that only verifies signatures).encrypted— encrypts the token without signing it. The payload is confidential, but there is no signature to verify integrity. This mode is narrower in purpose thansealedand should generally be avoided unless you have a specific compatibility requirement.
import { createAuth } from "@aura-stack/auth"
export const auth = createAuth({
oauth: [],
session: {
strategy: "jwt",
jwt: {
mode: "sealed",
},
},
})Stateful (database-backed) and hybrid session strategies are on the roadmap but not yet available. If your application requires
the ability to revoke a session server-side before its maxAge expires, track this on the roadmap rather than working around it
with a short maxAge.
maxAge
The maxAge option defines the session's lifetime in seconds. After this period, the session expires and the user must re-authenticate. The default is 15 days (60 * 60 * 24 * 15 seconds).
import { createAuth } from "@aura-stack/auth"
export const auth = createAuth({
oauth: [],
session: {
strategy: "jwt",
maxAge: 60 * 60 * 24 * 7, // 7 days
},
})maxDuration
The maxDuration option defines the maximum lifetime of a session in seconds, regardless of activity. After this period, the session expires and the user must re-authenticate.
import { createAuth } from "@aura-stack/auth"
export const auth = createAuth({
oauth: [],
session: {
strategy: "jwt",
maxDuration: 60 * 60 * 24 * 30, // 30 days
},
})expirationStrategy
The expirationStrategy option defines the renewal policy for the session/session expiration strategy. Determines how the session's lifetime is calculated and enforced
fixed: The session expires after a fixed duration from the time of creation.rolling: The session expiration is extended on each request, up to the maximum age.absolute: The session has a hard expiration time, regardless of activity.sliding: The session expiration is extended on each request, but cannot exceed the maximum expiration time.
import { createAuth } from "@aura-stack/auth"
export const auth = createAuth({
oauth: [],
session: {
strategy: "jwt",
expirationStrategy: "rolling",
},
})