Sessions persist a user's authenticated state across multiple requests to your application. This prevents users from having to repeatedly enter their credentials each time they interact with your application.

When authenticating users with Wristband, there are two distinct sessions that need to be maintained: authentication sessions and application sessions.

Authentication Session

When users authenticate with Wristband, Wristband creates an authentication session and stores it in the browser using a persistent cookie.

Cookie Scope: Authentication session cookies are tied to the Wristband tenant vanity domain that was used to call the Authorize API.
Behavior: When this cookie is present, calls to the Authorize API bypass the login screen and instantly authenticate the user.

The following Wristband workflows trigger the creation of an authentication session upon successful completion:

Signup (with Email Verification workflow policy)
User Activation
Login
New User Invite
Existing User Invite
Password Reset (with Immediate Login workflow policy)

Authentication Session Expiration

Authentication sessions expire after a period of inactivity or a set duration. Once a session expires, the user must log in again to access your application.

Wristband provides two configurable settings to manage this expiration window:

Idle Expiration Time: Automatically ends the session after a specific period of user inactivity.
Absolute Expiration Time: Enforces a hard limit on the total duration a session can remain active, regardless of user activity.

Idle Expiration Time

Idle expiration time tracks user dormancy within a Wristband auth session.

Defining Inactivity: Inactivity means the user has not triggered a request to Wristband's Authorize API. If a user leaves their device unattended, this timeout mitigates the risk of unauthorized access.
Configuration: You can customize this window in the Wristband dashboard up to a maximum limit of 90 days.
Extending the Session: If Wristband's Authorize API is called with an existing authentication session cookie present, the idle expiration time will be reset, thereby extending the idle window.

Absolute Expiration Time

Absolute expiration time sets a hard limit on how long a user's Wristband auth session can stay active.

Activity Independent: Unlike idle timeouts, the absolute timer cannot be extended or reset by interacting with the Authorize API.
Hard Session Termination: Once the limit is reached, the session expires immediately, and the user must reauthenticate.
Configuration: You can configure the absolute expiration time in the Wristband dashboard up to a maximum duration of 365 days.

Forcing Users to Reauthenticate

When calling the Authorize API you can force the user to reauthenticate, regardless of the presence of a an authentication session cookie, using the following two approaches:

1. Use the Prompt Parameter

The prompt parameter is an optional setting passed within a request to Wristband's Authorize API.

By default, when the prompt parameter is omitted from an authorization request, Wristband applies the following rules:

No Active Session: If an authentication session is missing or invalid, the user is redirected to the login page.
Active Session: If a valid authentication session is present, the user is automatically logged into the application.
- Exception: If a max_age value was specified in the authorization request and that time window has elapsed, the user will be redirected to the login page to reauthenticate.

However, if the prompt value is set to login, the user will always be forced to reauthenticate, even if an authentication session is present.

2. Use the Max Age Parameter

When calling the Authorize API, use the optional max_age parameter to enforce a strict amount of time that can elapse before a user must reauthenticate:

Unit: The max_age value is specified in seconds.
Behavior: Tracks the elapsed time since the user's last active login.
Enforcement: If the elapsed time exceeds the max_age value, Wristband bypasses the active auth session and forces the user to reauthenticate.

Application Session

In addition to the Wristband authentication session, your application should also store and manage its own separate session, referred to as the application session. The application session will be passed between the browser and your application, so your application doesn't have to reauthenticate the user with Wristband on each request.

Typically, you will store and associate the following data with an application session:

Access and refresh tokens
Access token expiration time
Some subset of user data for the currently logged-in user (i.e., userId, email, etc.)
Some subset of tenant data for the tenant to which the logged-in user belongs (i.e., tenantId, tenantDomainName, tenantCustomDomain, etc.)

Additional data may be tied to an application session depending on your platform's specific architecture and business logic.

Storage and maintenance of these application sessions depends primarily on your application type. Please refer to the following links for more information on how to manage your application sessions depending on your application type: