Install Auth SDK

Installation

Install the Wristband Auth SDK using your preferred package manager CLI:

npm install @wristband/nestjs-auth

yarn add @wristband/nestjs-auth

pnpm add @wristband/nestjs-auth

Configuration

Prerequisites

Before you can configure the SDK, you'll need to make sure you have the following values:

WRISTBAND_APPLICATION_VANITY_DOMAIN
WRISTBAND_CLIENT_ID
WRISTBAND_CLIENT_SECRET

If you went through the Set Up a Wristband Application guide, you should have been presented with these three values after the application was provisioned. If you don't have the above values on hand, you can retrieve them from the Wristband dashboard by following the steps in this guide.

Configure The SDK

Create a Wristband configuration file in your NestJS project (e.g. src/config/wristband.config.ts) and add an auth configuration factory. Update the config properties with the values for your application.

⚙️
Disabling Secure Cookies in Local Development
By default, WristbandAuth creates secure cookies (for tracking login state), 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 cookies for local development, set dangerouslyDisableSecureCookies: true in your auth config properties. However, be sure to re-enable secure cookies before deploying to production.

// src/config/wristband.config.ts

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

// Make sure your config values match what you configured in Wristband.
export const authConfig = registerAs('wristbandAuth', (): AuthConfig => ({
  clientId: '<WRISTBAND_CLIENT_ID>',
  clientSecret: '<WRISTBAND_CLIENT_SECRET>',
  wristbandApplicationVanityDomain: '<WRISTBAND_APPLICATION_VANITY_DOMAIN>',
}));

// src/config/wristband.config.ts

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

// Make sure your config values match what you configured in Wristband.
export const authConfig = registerAs('wristbandAuth', (): AuthConfig => ({
  clientId: '<WRISTBAND_CLIENT_ID>',
  clientSecret: '<WRISTBAND_CLIENT_SECRET>',
  wristbandApplicationVanityDomain: '<WRISTBAND_APPLICATION_VANITY_DOMAIN>',
  dangerouslyDisableSecureCookies: true,
}));

Register The Wristband Auth Service

Next, import the WristbandExpressAuthModule from the SDK and add it to your AppModule imports. Use the forRootAsync() method to configure the module with NestJS's async provider pattern, which will make the WristbandExpressAuthService available globally throughout your application via dependency injection.

// src/app.module.ts

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

// Wristband Config
import { authConfig } from './config/wristband.config';

@Module({
  imports: [
    // Add the ConfigModule to access .env files
    ConfigModule.forRoot({
      isGlobal: true,
      load: [authConfig], // <-- Register the Wristband configuration.
      envFilePath: env.NODE_ENV === 'production' ? '' : '.env',
      ignoreEnvFile: env.NODE_ENV === 'production',
    }),

    // Inject the Wristband configurations.
    WristbandExpressAuthModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (configService: ConfigService) => configService.get('wristbandAuth'),
      inject: [ConfigService],
    }),

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

export class AppModule {}