Install Auth SDK

Discover how to configure the Wristband SDK for your Nest.JS application.

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

Ensure you have gathered the following credentials and configuration values before initializing the SDK:

  • WRISTBAND_APPLICATION_VANITY_DOMAIN
  • WRISTBAND_CLIENT_ID
  • WRISTBAND_CLIENT_SECRET

These three environment variables are displayed immediately after provisioning your application via the Set Up a Wristband Application guide. If you do not have them on hand, you can locate them at any time in the dashboard by following the Manual Retrieval Guide.

Configure The SDK

Create a dedicated configuration file (such as src/config/wristband.config.ts) to initialize your auth configuration factory with your specific application values.

Disabling Secure Cookies in Local Development

WristbandAuth tracks session states using secure cookies that require an HTTPS connection by default. Although most desktop browsers waive this restriction for http://localhost, Safari strictly blocks secure cookies over unencrypted local HTTP connections.
To eliminate local login issues, add dangerouslyDisableSecureCookies: true to your development configuration properties. Always guarantee this flag remains disabled when deploying your application to a production environment.

// 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. Configure the module using the forRootAsync() method to implement NestJS's async provider pattern, making the WristbandExpressAuthService available globally across your entire application through 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 {}















What’s Next

Next, we’ll add session middleware to manage authenticated user sessions.

Did this page help you?