Add Auth Endpoints
Discover how to establish the mandatory authentication endpoints necessary for integrating your application with Wristband.
Implementing Wristband login and logout flows requires creating the following four Express endpoints using the SDK:
- Login Endpoint
- Callback Endpoint
- Logout Endpoint
- Session Endpoint
Login Endpoint
To begin authentication, the Login Endpoint creates an authorization payload and redirects traffic to Wristband's Authorize Endpoint. This routes the user to the hosted login interface to complete the flow.
Refer to the following code snippet to establish the Login Endpoint via the Wristband SDK.
// src/routes/auth-routes.ts
import express from 'express';
import { requireWristbandAuth, wristbandAuth } from '../wristband';
const router = express.Router();
// Login Endpoint
router.get('/auth/login', async (req, res, next) => {
// Call the Wristband login() method which will return a URL that should
// be used to redirect to Wristband's hosted login page.
const wristbandAuthorizeUrl = await wristbandAuth.login(req, res);
return res.redirect(wristbandAuthorizeUrl);
});
...Callback Endpoint
Following user validation, Wristband routes traffic back to your Callback Endpoint. Execute wristbandAuth.callback() to retrieve the CallbackResult object, which housing the session tokens and claims.
To initialize the user session, pass the callback payload into the session.fromCallback() function to populate user tokens and claims. Conclude the operation by invoking session.save().
Refer to the following code snippet to establish the Callback Endpoint via the Wristband SDK.
// src/routes/auth-routes.ts (continued)
...
// Callback Endpoint
router.get('/auth/callback', async (req, res, next) => {
// 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 CallbackResult.
const callbackResult = await wristbandAuth.callback(req, res);
const { callbackData, redirectUrl, type } = callbackResult;
// For some edge cases, such as if an invalid grant was passed to the token API,
// the SDK will return a redirect URL. Your code should redirect to it in order to
// restart the login flow.
if (type === 'redirect_required') {
return res.redirect(redirectUrl);
}
// 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.
req.session.fromCallback(callbackData)
await req.session.save();
// Once the Callback Endpoint has completed, we redirect to your app's
// default return URL (typically your app's home page) or to an explicit
// return URL, if one was specified in the original login request.
return res.redirect(callbackData.returnUrl || '<replace_with_a_default_return_url>');
});
...Logout Endpoint
When terminating a user session, your Logout Endpoint must perform three mandatory operations to purge all authenticated states:
- 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.
Refer to the following code snippet to establish the Logout Endpoint via the Wristband SDK.
// src/routes/auth-routes.ts (continued)
...
// Logout Endpoint
router.get('/auth/logout', async (req, res, next) => {
// Get all the necessary session data needed to perform the logout operation.
const { refreshToken, tenantCustomDomain, tenantName } = req.session;
// Clear your application's local session.
req.session.destroy()
// Call the Wristband logout() function and use the returned URL to 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 wristbandLogoutUrl = await wristbandAuth.logout(req, res, {
refreshToken,
tenantCustomDomain,
tenantName,
});
return res.redirect(wristbandLogoutUrl);
});
...Session Endpoint
To confirm session validity and retrieve user metadata, implement the Session Endpoint. The client application relies on this endpoint for two primary functional workflows:
- 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.
Refer to the following code snippet to establish the Session Endpoint via the Wristband SDK.
Important: This endpoint must be protected with authentication middleware.
// src/routes/auth-routes.ts (continued)
...
// Session Endpoint
// The `requireWristbandAuth` middleware ensures an authenticated session.
router.get('/auth/session', requireWristbandAuth, (req, res, next) => {
// 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.
res.header('Cache-Control', 'no-store');
res.header('Pragma', 'no-cache');
const sessionResponse = req.session.getSessionResponse();
return res.status(200).json(sessionResponse);
});
export default router;Map Auth Endpoints
After defining the authentication endpoints, import and mount them within the primary app.ts entry file of your Express application.
// src/app.ts
import express from 'express';
import { wristbandSession } from './wristband';
import authRoutes from './routes/auth-routes';
const app = express();
app.use(wristbandSession());
// New: Register your auth routes
app.use(authRoutes);
// Your other application setup...Register Your Login Endpoint and Callback Endpoint With Wristband
Proper redirect handling requires registering your application's Login and Callback URLs within the following two dashboard fields:
- Application Login URL
- Client Redirect URIs
The next sections explain how to update these two fields.
Updating the Application Login URL
To update the Application Login URL, follow these steps.
- From the Dashboard Home Page, select the appropriate application.

Figure 1: Select your Wristband application.
- On the Application Settings page, locate the Login URL field and set it to the URL of your application's Login Endpoint. Click Save when finished.

Figure 2: Configure the application Login URL.
Updating the Client Redirect URIs
To update the Client Redirect URIs, follow these steps.
- From the left-hand navigation menu, select "OAuth2 Clients" and choose the profile matching your application's Client ID.

Figure 3: Select the matching OAuth2 client.
- On the Edit Client page, go to the Redirect URIs section and click Add +. Enter the URL of your application's Callback Endpoint, then click Save.

Figure 4: Add the Callback Endpoint as a Redirect URI.
Updated 2 days ago
What’s Next
Now that your authentication endpoints are set up and configured, let's verify that they're working correctly.