B2C Auth With Multi-Tenancy

Wristband is built for multi-tenant authentication, making it a perfect fit for B2B applications where users are grouped into distinct organizations with specific roles and permissions. However, it adapts seamlessly to B2C scenarios where all users share a single tenant, register individually, and manage their own profiles. B2C authentication prioritizes personal identity, frictionless self-service, and optimized onboarding.

This guide walks you through configuring Wristband to deliver a consumer-grade B2C experience with minimal setup. At a high level, enabling a B2C flow requires the following steps:

• Use a Global Tenant in your Wristband application to serve all B2C users.
• Enable self-signup on the Global Tenant to support user-driven onboarding.
• Use Wristband's branding configurations and security policies to customize the authentication flows.
• Configure the Wristband SDK.
• Configure basic roles for end users and admin users.

Create Wristband Entities

To configure Wristband for B2C authentication, you will first need to create the following entities in the Wristband Dashboard:

• An Application
• An OAuth2 Client (for example purposes, this guide will use a Backend Server client type)
• A Global Tenant

The sections below detail how to create and configure each of these entities.

Create an Application

From the Wristband Dashboard homepage, click Add Application and complete the following fields in the modal:

• Display Name: This value identifies your application across the Wristband Dashboard, hosted login pages, and automated emails.
• Name: This field will be used when constructing your application's vanity domain. This field is immutable and can't be changed after the application is created.
• Enable Production Environment Validations: Enable this setting if you plan to use this application in production. Doing so enforces secure configuration defaults tailored for production environments. Note: This setting is immutable and cannot be changed after the application is created.
• Application Login URL: The login URL is your application endpoint that redirects users to the Wristband Authorize endpoint. For local testing, you can use a development address like http://localhost:3001/login. Production URLs must use the secure https protocol and cannot point to localhost (e.g.,https://yourapp.com/login).

Copy The Application Vanity Domain

Navigate to your newly created application from the Dashboard homepage to open its Application Settings page. Locate and copy the Application Vanity Domain value; you will need this to configure the Wristband Auth SDK.

Disable Application-Level Self-Signup

Ensure that self-signup is disabled at the application level. Enabling this feature allows end users to self-provision new tenants within your application. Because this is a B2C application, all users must belong to a single, shared tenant rather than creating their own isolated environments.

Create an OAuth2 Client

From the left navigation menu of your application view, select OAuth2 Clients. Click Add Client and complete the following fields in the modal:

• Type: Select Backend Server for the purposes of this guide. Ensure you choose the appropriate type if your own application uses a different architectural pattern.
• Client Name: Enter any descriptive name. This value serves as a human-readable identifier for your client within the Wristband Dashboard.
• Redirect URIs: The redirect URI specifies the endpoint within your application where Wristband routes users after successful authentication. For local development, this can point to a localhost address (e.g., http://localhost:3001/auth/callback). In production, this must use a secure https scheme (e.g., https://yourapp.com/auth/callback).

Copy Client ID and Secret

After creating the client, copy the Client ID and Client Secret values displayed in the success dialog; you will need them to configure your Wristband SDK. If you ever lose your client secret, you can rotate it from the dashboard to generate a new one.

Create the Global Tenant

To deliver a B2C authentication experience, you must provision a single Global Tenant where all consumer accounts will reside. Navigate to your application view, select Tenants from the left navigation menu, click Add Tenant, and complete the following fields in the modal:

• Tenant Type: This value must be set to "Global".
• Display Name: Enter a descriptive name for your tenant. Wristband displays this value across the dashboard, hosted pages, and automated emails. For B2C applications, this should match your product or service name.
• Name: This value is used to construct your unique tenant vanity domain and cannot be modified after creation. While the field itself is immutable, you can change the public-facing URL in the future by configuring custom domains instead.

Enable Self-Signup For The Global Tenant

On the Tenant Settings page, switch the Enable Tenant-Level Signup toggle to the active position. This activates self-signup and makes the Tenant Signup Page accessible to your users.

Customize Your Application

Wristband offers extensive customization options to tailor your B2C application experience. Most of these configurations can be managed globally at the application level through the Dashboard. The only exception is custom domains, which require individual tenant-level configuration.

Explore our documentation to learn how to customize different aspects of your B2C application.

• Social Logins
• Branding
• Tenant Custom Domains
• Custom Email Domains

Configure the Wristband SDK

Once your application is configured and customized in the Dashboard, you can initialize the Wristband SDK in your codebase. The following sections walk through setting up the SDK for a B2C workflow.

While Wristband supports multiple frameworks, this guide uses the Express SDK for its examples. The structural patterns remain consistent across all Wristband SDKs, allowing you to easily apply these core principles to your preferred stack.

For step-by-step implementation details tailored to your specific setup, refer to our framework-specific quickstart guides.

SDK Initialization

When initializing the WristbandAuth instance in your Express application, configure it with the following AuthConfig properties:

// wristband-auth.ts

import { createWristbandAuth } from '@wristband/express-auth';
import { AuthConfig } from './types';

const authConfig: AuthConfig = {
  // Use the client credentials and application vanity domain from earlier.
  clientId: '<your-client-id>',
  clientSecret: '<your-client-secret>',
  wristbandApplicationVanityDomain: '<your-application-vanity-domain>'
};

export const wristbandAuth = createWristbandAuth(authConfig);

Login Endpoint Configuration

Configure your backend's Login Endpoint to redirect users to your Global Tenant's login page. The precise redirect logic depends on whether you are using a custom domain for your Global Tenant.

Configuration Without a Custom Domain

Create a LoginConfig object and pass the name of your previously created Global Tenant into the defaultTenantName parameter.

// app.ts

import { CallbackResultType } from '@wristband/express-auth';
import wristbandAuth from './wristband-auth';

...

app.get('/auth/login', async (req, res, next) => {
  try {
    // Replace the value of "defaultTenantName" with your Global Tenant's name.
    const loginConfig = { defaultTenantDomainName: '<your-global-tenant-name>' };

    const loginUrl = await wristbandAuth.login(req, res, loginConfig);
    res.redirect(loginUrl);
  } catch (err) {
    console.error(err);
    next(err);
  }
});

...

Configuration With a Custom Domain

If you are utilizing a custom domain for your Global Tenant, instantiate a LoginConfig object with the defaultTenantCustomDomain parameter set to that custom domain.

// app.ts

import { CallbackResultType } from '@wristband/express-auth';
import wristbandAuth from './wristband-auth';

...

app.get('/auth/login', async (req, res, next) => {
  try {
    // Replace the value of "defaultTenantCustomDomain" with your Global Tenant's
    // custom domain.
    const loginConfig = { defaultTenantCustomDomain: '<your-global-tenant-custom-domain>' };

    const loginUrl = await wristbandAuth.login(req, res, loginConfig);
    res.redirect(loginUrl);
  } catch (err) {
    console.error(err);
    next(err);
  }
});

...

Logout Endpoint Configuration

Similar to the login flow, configure your backend’s Logout Endpoint to always redirect users to the Wristband Logout Endpoint for your Global Tenant.

Configuration Without a Custom Domain

Create a LogoutConfig object and set the tenantName parameter to the name of your previously created Global Tenant.

// Logout endpoint
app.get('/auth/logout', async (req, res, next) => {
  const { session } = req;
  const { refreshToken } = session;
  const logoutConfig = { refreshToken, tenantDomainName: '<your-global-tenant-name>' };
  res.clearCookie('session');
  res.clearCookie('CSRF-TOKEN');
  session.destroy();

  try {
    const logoutUrl = await wristbandAuth.logout(req, res, logoutConfig);
    return res.redirect(logoutUrl);
  } catch (err) {
    console.error(err);
    return next(err);
  }
});

Configuration With a Custom Domain

If you are utilizing a custom domain for your Global Tenant, instantiate a LogoutConfig object with the tenantCustomDomain parameter set to that custom domain.

// Logout endpoint
app.get('/auth/logout', async (req, res, next) => {
  const { session } = req;
  const { refreshToken } = session;
  const logoutConfig = { refreshToken, tenantCustomDomain: '<your-global-tenant-custom-domain>'};
  res.clearCookie('session');
  res.clearCookie('CSRF-TOKEN');
  session.destroy();

  try {
    const logoutUrl = await wristbandAuth.logout(req, res, logoutConfig);
    return res.redirect(logoutUrl);
  } catch (err) {
    console.error(err);
    return next(err);
  }
});

With your login and logout endpoints updated, users will now land on the Global Tenant login page when signing in, and seamlessly route to the Global Tenant logout endpoint when signing out.

Configure RBAC

Create Roles for Each Persona

B2C applications typically utilize roles to enforce authorization boundaries. You can easily manage and create roles representing different user personas directly inside the Wristband Dashboard. For example, if your application features basic user and administrative tiers, you would create the following two roles:

• End User: Assigned to the standard end users of your application. This role permits basic operations but excludes elevated privileges required for administrative actions.
• Admin: Assigned to application administrators, such as internal creators or employees. This role grants full access to elevated capabilities and administrative actions within the application.

To create roles, navigate to your application view and select Authorization > Roles from the left navigation menu. Click Add Role and complete the following fields for each persona:

• Role Name: Enter a descriptive name for the role. This value serves as a unique, human-readable identifier and cannot be changed after creation.
• Display Name: The Wristband Dashboard uses this name whenever it displays the role to administrators.
• Tenant Visibility: Controls which tenants can access this role. Set this value to All to ensure all tenants across the application—including your Global Tenant—have access.

Assigning Permissions and Boundaries

After creating your roles, you must determine which permissions to assign to them. Wristband categorizes permissions into two distinct types: custom and predefined.

Custom Permissions

Custom permissions are created by you to control access to specific resources within your application. For example, a document resource might use CRUD-mapped permissions like document:create, document:read, document:update, and document:delete.

Because these represent internal business logic, your application is entirely responsible for enforcing custom permission checks; Wristband does not evaluate authorization decisions for custom permissions. If your application's access model is simple, you can omit custom permissions entirely and make authorization decisions based strictly on the user's assigned roles.

Create Custom Permissions

To create custom permissions within the Dashboard, navigate to the Application View and select "Authorization" -> "Permissions" from the left navigation menu. Click the "Add Permission" button and fill out the following fields:

• Permission Name: The unique identifier for your permission. While you can use any value, we recommend following a <resource>:<verb> naming convention (e.g., document:read to allow users to view a document resource).
• Description: A description of the permission.
• Tenant Visibility: Controls tenant access for this permission. For B2C applications, typically set this value to None since your roles are managed globally at the application level. You only need to select All if you plan to define roles at the tenant level that require this permission.

Assign Custom Permissions to Roles

To assign custom permissions to a role, navigate to your application view and select Authorization > Roles from the left navigation menu. Click the target role in the Custom Roles table, scroll down to the Permissions section, select your custom permission from the Add Permissions drop-down, and click Add Permissions.

Predefined Permissions

Predefined permissions are built-in scopes managed by Wristband to secure its own system entities, such as users, tenants, and applications. When your application calls Wristband APIs on behalf of an end user, the user's access token must include the required predefined permissions for that endpoint. For example, to query the Wristband Get User API, the executing user's session token must be associated with the user:read permission.

Wristband also utilizes permission boundaries to define the precise operational scope of a granted permission. For example, if a role contains the user:read permission, the permission boundary determines which users within the application environment can actually be read. Wristband provides three out-of-the-box permission boundaries:

1. Self: The Self permission boundary restricts actions exclusively to resources directly owned by or associated with the authenticating user.
2. Tenant: The Tenant permission boundary restricts actions exclusively to resources owned by or associated with the specific tenant that the user belongs to.
3. Application: The Application permission boundary expands actions to include all resources owned by or associated with the entire application, spanning across all tenants.

Returning to our example of the End User and Admin roles, assigning predefined permissions requires mapping them to the correct permission boundaries. The table below details the recommended permission boundaries for each role:

Assign Predefined Permissions to Roles

To assign predefined permissions to a role, navigate to your application view and select Authorization > Roles from the left navigation menu. Click the target role in the Custom Roles table, scroll down to the Permissions section, select your predefined permission from the Add Permissions dropdown, and click Add Permissions.

Assign a Permission Boundary to a Role

To assign a permission boundary to a role, navigate to your application view and select Authorization > Roles from the left navigation menu. Click the target role in the Custom Roles table, and select your preferred boundary from the Permission Boundary drop-down.

Assigning Roles To Users

B2C applications can distribute and assign user roles through multiple mechanisms. Below, we explore the most common approaches to managing role allocation.

Configure Default Signup Roles

When users register through the self-signup flow, you will typically want to assign them a default role. To configure this behavior, navigate to Authorization > Role Assignment Policies in the left navigation menu of the Wristband Dashboard. Update the Default Signup Roles field with your preferred role. Once saved, all newly provisioned users will automatically receive this assignment.

Manually Assign Roles to Invited Users

When manually inviting users to your application, you can explicitly select which roles to assign them. This allows existing administrators to safely onboard users who require elevated privileges, such as other administrators.

To send an invitation from the Wristband Dashboard, select Users from the left navigation menu, scroll to the New User Invitations section, and configure the following parameters:

1. Tenant: This is the tenant under which the invited user will be provisioned.
2. Email: The email to which the invite will be sent.
3. Roles to Assign: List of roles that will be assigned to the user after they accept the invite.