---
updatedAt: 2026-10-13T19:04:58.000Z
agentTools:
  projectIndex: https://docs.wristband.dev/llms.txt
---

# Add Session Middleware

Set up session middleware to manage your application's authenticated sessions.

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, register a session configuration factory in your Wristband configuration file. You'll need to provide a secret (at least 32 characters long) for the `secrets` value. You can generate a secure secret key at <Anchor target="_blank" href="https://securepassword.dev?type=secret_key"><https://securepassword.dev></Anchor>.

<Callout icon="far fa-circle-info" theme="info">
  ### 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.
</Callout>

```typescript Session Options With Secure Cookies
// src/config/wristband.config.ts

import { registerAs } from '@nestjs/config';
import type { AuthConfig, SessionOptions } from '@wristband/nestjs-auth';

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

// ADD: Session options to use in both Session Middleware and Auth Guards.
const sessionOptions: SessionOptions = {
  secrets: '<your-generated-secret>',
};

// ADD: Session configuration for the session middleware.
export const sessionConfig = registerAs(
  'wristbandSession',
  (): SessionOptions => sessionOptions,
);
```
```typescript Session Options With Secure Cookies Disabled
// src/config/wristband.config.ts

import { registerAs } from '@nestjs/config';
import type { AuthConfig, SessionOptions } from '@wristband/nestjs-auth';

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

// ADD: Session options to use in both Session Middleware and Auth Guards.
const sessionOptions: SessionOptions = {
  secrets: '<your-generated-secret>',
  secure: false,
};

// ADD: Session configuration for the session middleware.
export const sessionConfig = registerAs(
  'wristbandSession',
  (): SessionOptions => sessionOptions,
);
```

## Register The Session Module and Middleware

Next, do the following:

1. Import the `WristbandExpressSessionModule` and add it to your `AppModule` imports. Configure it with `forRootAsync()` using NestJS's async provider pattern.
2. Import the `WristbandExpressSessionMiddleware` and apply it globally to all routes using NestJS's middleware consumer.

<Callout icon="far fa-circle-info" theme="info">
  ### **NestJS Version 10.x Note**

  If you're using NestJS 10.x, use `.forRoutes('*')` instead of `.forRoutes('{*splat}')` for the middleware consumer.
</Callout>

```typescript Register Session Module and Middleware
// src/app.module.ts

import { ConfigModule, ConfigService } from '@nestjs/config';
import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
import { env } from 'node:process';
import { WristbandExpressAuthModule } from '@wristband/nestjs-auth';
import {
  WristbandExpressSessionMiddleware,
  WristbandExpressSessionModule
} from '@wristband/nestjs-auth/session';

// Import the session configuration.
import { authConfig, sessionConfig } from './config/wristband.config';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      load: [authConfig, sessionConfig], // <-- Register the session configuration.
      envFilePath: env.NODE_ENV === 'production' ? '' : '.env',
      ignoreEnvFile: env.NODE_ENV === 'production',
    }),
    WristbandExpressAuthModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (configService: ConfigService) => configService.get('wristbandAuth'),
      inject: [ConfigService],
    }),

    // Inject the Wristband configurations for Session Middleware.
    WristbandExpressSessionModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (configService: ConfigService) => configService.get('wristbandSession'),
      inject: [ConfigService],
    }),

    // ...any project-specific modules...
  ],
})

export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    // ADD: Configure the middleware for your app on all routes.
    consumer.apply(WristbandExpressSessionMiddleware).forRoutes('{*splat}');
  }
}
```

<br />

<HTMLBlock>{`
<style>
.UpdatedAt {
  display: none;
}
</style>
`}</HTMLBlock>