Add Session Middleware

To manage the user's authenticated state, you'll need to add Wristband's session middleware to your application. This middleware attaches a req.session object to each incoming request, which stores information about the authenticated user. The session data is securely stored in an encrypted cookie, and on subsequent requests, the middleware automatically decrypts the cookie and restores the session state.

Configure Session Middleware

To enable session management, add the Wristband SDK’s session middleware to your Wristband configuration file via the createWristbandSession() function. You'll need to provide a secret (at least 32 characters long) for the secrets value. You can generate a secure secret using 1Password's password generator .

⚙️
Disabling Secure Session Cookies in Local Development
By default, session cookies are marked as secure, meaning they are only sent over HTTPS connections. Most browsers make an exception for localhost and allow secure cookies to be sent over HTTP (e.g., http://localhost). However, some browsers, such as Safari, enforce stricter rules and never send secure cookies over HTTP, even for localhost.
If you need to disable the secure flag for local development, set secure: false in your session options. However, be sure to restore secure: true in production to protect session data.

// src/wristband.ts

import { createWristbandAuth } from '@wristband/express-auth';
import { createWristbandSession } from '@wristband/express-auth/session';

export const wristbandAuth = createWristbandAuth({
  clientId: '<WRISTBAND_CLIENT_ID>',
  clientSecret: '<WRISTBAND_CLIENT_SECRET>',
  wristbandApplicationVanityDomain: '<WRISTBAND_APPLICATION_VANITY_DOMAIN>',
});

// NOTE: Session options can be used in both Session and Auth Middlewares.
const sessionOptions = {
  secrets: '<your-generated-secret>',
};

// Initialize the session middleware with your configured options.
export function wristbandSession() {
  return createWristbandSession(sessionOptions);
}

// src/wristband.ts

import { createWristbandAuth } from '@wristband/express-auth';
import { createWristbandSession } from '@wristband/express-auth/session';

export const wristbandAuth = createWristbandAuth({
  clientId: '<WRISTBAND_CLIENT_ID>',
  clientSecret: '<WRISTBAND_CLIENT_SECRET>',
  wristbandApplicationVanityDomain: '<WRISTBAND_APPLICATION_VANITY_DOMAIN>',
  dangerouslyDisableSecureCookies: true,
});

// NOTE: Session options can be used in both Session and Auth Middleware.
const sessionOptions = {
  secrets: '<your-generated-secret>',
  secure: false,
};

// Initialize the session middleware with your configured options.
export function wristbandSession() {
  return createWristbandSession(sessionOptions);
}

Register Session Middleware

Next, register the Wristband session middleware with your Express application.

// src/app.ts

import express from 'express';
import { wristbandSession } from './wristband';

const app = express();

// Register the session middleware to enable encrypted, cookie-based sessions.
app.use(wristbandSession());

// Your other application setup...