For this section, we'll define a session as a period during which a user interacts with an application after successfully logging in. It begins when the user logs in and ends when they log out or when the session expires due to inactivity or other defined criteria. During this session, the user can access and use the application without needing to repeatedly enter their login credentials.

In Wristband, there are two separate notions of a session: authentication sessions and application sessions.

Authentication Session

Wristband maintains an authentication (auth) session for any user who logs into your application, ensuring a streamlined SSO experience for any inbound SSO integrations. Authentication sessions are stored in cookies in the browser and are associated with the following domains:

• Multi-tenant applications: Authentication session cookies are associated with the Wristband tenant vanity domain, or with the tenant custom domain if custom domains are active for your application.
• Single-tenant applications: Authentication session cookies are associated with the Wristband application vanity domain, or with the application custom domain if custom domains are active for your application.

When an auth session cookie is present, the user will bypass the login screen when calling Wristband's Authorize API and immediately be logged into the application.

The following Wristband workflows lead to an auth session being created:

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

Authentication Prompt Options

The prompt parameter is an optional parameter that you can pass in an authorization request when redirecting to Wristband's Authorize API. It can control the behavior of the login process by telling Wristband how to handle the user's interaction during the authorization code flow. The following prompt values are supported in Wristband:

By default, when the prompt parameter is omitted from the authorization request, the following rules are applied:

• If an auth session is not present or invalid, then the user will be redirected to the login page.
• If the auth session is both present and valid, then automatically log the user into the application. There is one exception: when a max age value was specified in the authorization request and the max age time has elapsed. In that case, the user will be redirected to the login page.

Authentication Max Age

Your application can also optionally specify a max_age parameter when making an authorization request to Wristband. This controls the maximum authentication age by specifying the allowable elapsed time in seconds since the last time the user was actively authenticated. If the elapsed time is greater than this value, then the end user will be redirected to the login page to reauthenticate.

Auth Session Expiration

Auth session expiration, also known as session timeout, refers to the automatic termination of a user's authenticated session with Wristband after a predefined period of inactivity or a specific duration. When the auth session expires, the user is required to log in again to access your application.

Wristband provides two settings you can configure to determine the duration of the expiration window: idle expiration time and absolute expiration time.

Idle Expiration Time

Idle expiration time, also known as inactivity timeout, refers to the period of inactivity by a user within a Wristband auth session. Inactivity means that the user has not interacted with Wristband's Authorize API. If the user remains idle for a specific duration, the auth session expires, and they will need to reauthenticate on the login page the next time the application redirects to the Authorize API. This mitigates the risk of unauthorized access if a user leaves their session unattended, especially in scenarios where others may have access to their device.

The maximum possible idle expiration time allowed is 90 days, and the exact value can be configured in the Wristband dashboard.

Your application can extend the duration of the idle expiration window for any user's active authentication session by interacting with Wristband's Authorize API. For example, if your application stores access and refresh tokens in a session cookie, and both tokens expired, then the next time your user tried to perform an action that required a token, the application would initiate a new authorization code flow with Wristband to get new tokens. Since the user's auth session with Wristband exists and has not exceeded the idle expiration timeout window, Wristband would allow the user to bypass entering their credentials and send the user back into the application with the new tokens.

Absolute Expiration Time

Absolute expiration time, also referred to as maximum session duration, is the maximum amount of time a user's auth session with Wristband is allowed to remain active, regardless of any user activity or interaction with Wristband's Authorize API. Once this predefined duration is reached, the session expires, and the user is required to log in again.

The primary purpose of this absolute timeout is to prevent the potential for indefinitely long sessions and reduce the risk of unauthorized access. The maximum possible absolute expiration time allowed is 365 days, and the exact value can be configured in the Wristband dashboard.

📘

Note About Idle and Absolute Expirations

When configuring auth session expiration times in the Wristband dashboard, the idle expiration time must always be set to a value that is lower than the absolute expiration time.

Application Session

Even though your application will use Wristband to authenticate users, your application should also keep track of the users that are logging in to your application. Your application can store and manage its own separate session independently of the Wristband auth session. This is called the application session. The typical data you would store and associate with an application session is:

• Access and refresh tokens (and optionally the ID token)
• 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.)

There is more data that you could associate with an application session, but that would be context-dependent on what your application is trying to accomplish.

Handling the storage and maintenance of application sessions depends on the type of application you have:

• Backend Server Application Sessions
• Single Page App Application Sessions
• Native Application Sessions