Add Auth Endpoints
Set up the required authentication endpoints to integrate your NestJS application with Wristband.
Implement the login and logout flows by using the Wristband SDK to create these four endpoints in your Nest.JS application:
- Login Endpoint
- Callback Endpoint
- Logout Endpoint
- Session Endpoint
Login Endpoint
The Login Endpoint handles all incoming authentication requests for your application. It constructs the OAuth2 authorization URL and redirects the user to the Wristband Authorize Endpoint, which then routes them directly to Wristband's hosted login page to complete authentication.
The code snippet below demonstrates how to implement this endpoint using the Wristband SDK:
// src/app/api/auth/login/route.ts
import type { NextRequest } from 'next/server';
import { wristbandAuth } from 'src/wristband';
// Login Endpoint
export async function GET(request: NextRequest) {
// Call the Wristband login() method which will return a NextResponse with the
// URL that should be used to redirect to Wristband's hosted login page.
return await wristbandAuth.appRouter.login(request);
}Callback Endpoint
Upon successful authentication, Wristband redirects the user to your application's Callback Endpoint. Invoking wristbandAuth.appRouter.callback() processes this incoming request and returns a CallbackResult object containing the user's tokens and claims.
To initialize the user's session, pass this callback data into the session.fromCallback() function, which hydrates the session with the user's claims and tokens. Finally, persist the session by calling session.saveToResponse().
The code snippet below demonstrates how to implement this callback logic using the Wristband SDK:
// src/app/api/auth/callback/route.ts
import { NextRequest } from 'next/server';
import { getRequestSession, wristbandAuth } from 'src/wristband';
// Callback Endpoint
export async function GET(request: NextRequest) {
// Call the Wristband callback() method to check if the user
// successfully authenticated. If the user did authenticate successfully,
// the user's tokens and claims can be retrieved from the callback result.
//
// The second argument returns the URL that the SDK sets as the redirect
// location on the response after a successful login: your app's default
// return URL (typically your app's home page), or an explicit return URL,
// if one was specified in the original login request.
const callbackResult = await wristbandAuth.appRouter.callback(
request,
(req, data) => {
return data.returnUrl || '<replace_with_a_default_return_url>';
}
);
const { callbackData, response, type } = callbackResult;
// Some edge cases require a redirect to the Login Endpoint.
if (type === 'redirect_required') {
return response;
}
// Create a session for the authenticated user. If needed, custom fields can
// be stored in the session using the customFields parameter of the
// fromCallback() method.
const session = await getRequestSession(request);
session.fromCallback(callbackData);
// To complete the Callback Endpoint, save the user's session before redirecting.
return await session.saveToResponse(response);
}Logout Endpoint
When a user logs out, you must completely clear all authenticated states associated with their session. The Logout Endpoint achieves this by executing three essential tasks:
- Clear the application's local session state.
- Revoke any refresh tokens associated with the user.
- Redirect to Wristband's Logout Endpoint to terminate the user's Wristband auth session.
Below is a code snippet showing how to use Wristband's SDK to implement the Logout Endpoint.
// src/app/api/auth/logout/route.ts
import type { NextRequest } from 'next/server';
import { getRequestSession, wristbandAuth } from 'src/wristband';
// Logout Endpoint
export async function GET(request: NextRequest) {
// Get all the necessary session data needed to perform the logout operation.
const session = await getRequestSession(request);
const logoutConfig = {
refreshToken: session.refreshToken,
tenantName: session.tenantName,
};
// Call the Wristband logout() function to get the NextResponse with the URL that
// will redirect to Wristband's Logout Endpoint. This will delete Wristband's session
// that is associated to the authenticated user. When Wristband is done logging out
// the user it will redirect back to your application's login URL or to the
// explicitly provided redirect URL.
const response = await wristbandAuth.appRouter.logout(request, logoutConfig);
// To complete the Callback Endpoint, destroy your application's local
// session before redirecting.
return await session.destroyToResponse(response);
}Session Endpoint
The Session Endpoint verifies whether an incoming request contains a valid active session. If a valid session is found, it returns a response containing the user's session data. The frontend relies heavily on this endpoint for two primary purposes:
- To allow the frontend to determine whether the user has a valid session.
- To provide the frontend with the user's session data for use within the browser.
The code snippet below demonstrates how to implement the Session Endpoint using the Wristband SDK to validate sessions and expose data to your frontend:
// src/app/api/auth/session/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { getRequestSession } from 'src/wristband';
// Session Endpoint
export async function GET(request: NextRequest) {
// Call the getSessionResponse() method to extract the user's
// session data and populate a SessionResponse. If needed, you can add
// additional data to the SessionResponse by using the metadata parameter
// of the getSessionResponse() method.
const session = await getRequestSession(request);
const sessionResponse = session.getSessionResponse();
return NextResponse.json(sessionResponse);
}Register Your Login Endpoint and Callback Endpoint With Wristband
For several authentication flows, Wristband must redirect back to your application's Login and Callback endpoints. To ensure these redirects work correctly, you must provide Wristband with their exact URLs by updating the following two fields in your Wristband dashboard:
- Application Login URL
- Client Redirect URIs
The sections below outline how to configure both of these fields within your dashboard.
Updating the Application Login URL
To update the Application Login URL, follow these steps.
- From the Dashboard Home Page, select the appropriate application.

Figure1: Select your Wristband application.
- Locate the Login URL field:
- On the Application Settings page: Scroll down to find the Login URL field.
- Configure your endpoint: Input the full URL that points to your application's Login Endpoint.
- Save your changes: Click the Save button at the bottom of the page to apply the update.

Figure 2: Configure the application Login URL.
Updating the Client Redirect URIs
- Follow these steps to update your Client Redirect URIs:
- Open OAuth2 Clients: Select OAuth2 Clients from the left navigation bar.
- Choose your client: Select the specific client whose ID matches the client ID registered with your application's SDK.

Figure 3: Select the matching OAuth2 client.
- Add a new URI:
- On the Edit Client page: Scroll down to the Redirect URIs section and click the Add+ button.
- Enter your callback: Input the full URL of your application's Callback Endpoint into the new field.
- Save your changes: Click the Save button to finalize the configuration.

Figure 4: Add the Callback Endpoint as a Redirect URI.
Updated 15 days ago
What’s Next
Before testing these authentication endpoints, you'll need to set up auth middleware to secure your Session Endpoint.