Understanding Session Management

Sessions maintain a user's authenticated state across multiple requests, allowing them to interact with your application without repeatedly entering their credentials.

When authenticating users with Wristband, two distinct types of sessions are involved: authentication sessions and application sessions. Each serves a different purpose in maintaining the user's authenticated state.

Authentication Sessions

When a user successfully authenticates with Wristband, Wristband creates an authentication session and stores it in the browser using a persistent cookie.

Cookie Scope: The authentication session cookie is scoped to the Wristband tenant vanity domain used to call the Authorize API.
Behavior: When the cookie is present and valid, subsequent calls to the Authorize API can authenticate the user without displaying the login screen again.

The following Wristband workflows create an authentication session upon successful completion:

Signup (when Email Verification is configured as the verification step)
User Activation
Login
New User Invite
Existing User Invite
Password Reset (when Immediate Login is enabled)

Authentication Session Expiration

Authentication sessions expire after a period of inactivity or a predefined maximum duration. Once a session expires, the user must authenticate again to continue accessing your application.

Wristband provides two configurable settings to control authentication session expiration:

Idle Expiration Time: Expires the session after a specified period of user inactivity.
Absolute Expiration Time: Expires the session after a fixed duration, regardless of user activity.

Idle Expiration Time

Idle expiration determines how long an authentication session can remain inactive before it expires.

Defining Inactivity: Inactivity means the user has not made a request to Wristband's Authorize API. This timeout helps reduce the risk of unauthorized access if a user leaves their device unattended.
Configuration: You can configure the idle expiration time in the Wristband Dashboard, up to a maximum of 90 days.
Extending the Session: When the Authorize API receives a request with a valid authentication session cookie, Wristband resets the idle expiration timer, extending the session's idle window.

Absolute Expiration Time

Absolute expiration sets a fixed limit on how long an authentication session can remain active.

Independent of Activity: Unlike idle expiration, absolute expiration cannot be extended or reset by requests to the Authorize API.
Session Termination: When the configured limit is reached, the session expires, and the user must authenticate again.
Configuration: You can configure the absolute expiration time in the Wristband Dashboard, up to a maximum of 365 days.

Controlling Reauthentication

You can require users to reauthenticate when calling the Authorize API, even if they already have an active authentication session. Wristband supports two parameters for controlling reauthentication: prompt and max_age.

1. Use the `prompt` Parameter

The optional prompt parameter controls whether Wristband can reuse an existing authentication session.

When prompt is omitted, Wristband behaves as follows:

No Active Session: If the authentication session is missing or invalid, the user is redirected to the login page.
Active Session: If a valid authentication session exists, Wristband authenticates the user without displaying the login page.
max_age Exception: If the authorization request includes max_age and the time since the user's last authentication exceeds that value, Wristband requires the user to reauthenticate.

When prompt is set to login, Wristband always requires the user to reauthenticate, even if a valid authentication session exists.

2. Use the `max_age` Parameter

The optional max_age parameter specifies the maximum amount of time that can elapse since the user's last authentication before reauthentication is required.

Unit: The max_age value is specified in seconds.
Behavior: Wristband evaluates the time elapsed since the user's last authentication.
Enforcement: If the elapsed time exceeds the specified max_age, Wristband requires the user to reauthenticate, even if an active authentication session exists.

Application Sessions

In addition to the Wristband authentication session, your application should maintain its own session, referred to as the application session. This session allows your application to maintain the user's authenticated state between requests without requiring the user to reauthenticate with Wristband each time.

An application session typically stores the following information:

Tokens: Access and refresh tokens.
Token Metadata: The access token's expiration time.
User Data: Relevant information about the authenticated user, such as userId and email.
Tenant Data: Relevant information about the user's tenant, such as tenantId and tenantName.

Depending on your application's architecture and business requirements, you may store additional information in the application session.

How you store and manage application sessions depends on your application type. Refer to the guides below for implementation details: