Backend server auth SDKs don't add routes to your application on their own. Instead, your backend server exposes a small set of auth endpoints, and each endpoint calls into the SDK to do the auth-specific work. This keeps you in control of your routes while the SDK handles the communication with Wristband.

The route path for each endpoint is up to you. The Login Endpoint and Callback Endpoint must match the loginUrl and redirectUri values in your SDK configuration.

See the Login URL and Redirect URI section of Backend SDK Configuration for more on loginUrl and redirectUri.

Login Endpoint

Your frontend redirects users to the Login Endpoint whenever they need to log in. For example:

GET https://customer01.yourapp.io/auth/login

The SDK's login function determines which tenant the user is logging into, creates a Login State Cookie to track the login request, and builds the redirect that sends the user to Wristband to authenticate. Your Login Endpoint returns that redirect.

For example, using the Express Auth SDK:

app.get('/auth/login', async (req, res) => {
  const loginUrl = await wristbandAuth.login(req, res);
  res.redirect(loginUrl);
});

See Login for details.

Callback Endpoint

After the user authenticates, Wristband redirects them to the Callback Endpoint. For example:

GET https://customer01.yourapp.io/auth/callback?state=f983yr893hf89ewn0idjw8e9f&code=shcsh90jf9wc09j9w0jewc

The SDK's callback function verifies the request against the Login State Cookie, exchanges the authorization code for tokens, and retrieves the user's data from Wristband. It then returns one of two results:

• Completed: Login succeeded, and the result includes the tokens and user data. Your Callback Endpoint creates the application session from this data and redirects the user into your application.
• Redirect required: The login can't be completed, such as when the Login State Cookie has expired. Your Callback Endpoint redirects the user back to the Login Endpoint to start a new login.

For example, using the Express Auth SDK:

app.get('/auth/callback', async (req, res) => {
  const callbackResult = await wristbandAuth.callback(req, res);
  const { callbackData, reason, redirectUrl, type } = callbackResult;

  // Certain edge cases require a redirect back to the Login Endpoint.
  if (type === 'redirect_required') {
    console.debug(reason);
    res.redirect(redirectUrl);
    return;
  }

  // Create the application session from the callback data.
  req.session.fromCallback(callbackData);
  await req.session.save();

  // Send the user back into your application.
  res.redirect(callbackData.returnUrl || '<your_app_home_url>');
});

See Callback for details.

Logout Endpoint

Your frontend redirects users to the Logout Endpoint when they log out. For example:

GET https://customer01.yourapp.io/auth/logout

Your Logout Endpoint destroys the application session, and the SDK's logout function revokes the user's refresh token and builds the redirect that sends the user to Wristband to end their Wristband auth session. Your Logout Endpoint returns that redirect.

For example, using the Express Auth SDK:

app.get('/auth/logout', async (req, res) => {
  const { refreshToken, tenantCustomDomain, tenantName } = req.session;

  // Always destroy your application's session.
  req.session.destroy();

  const logoutUrl = await wristbandAuth.logout(req, res, {
    refreshToken,
    tenantCustomDomain,
    tenantName
  });

  res.redirect(logoutUrl);
});

See Logout for details.

Session Endpoint

The Session Endpoint is only needed when your frontend uses a Wristband frontend SDK. Server-rendered applications, such as traditional Django apps using templates, don't need it. Wristband frontend SDKs call the Session Endpoint to check whether the user is authenticated and to load their session data. For example:

GET https://customer01.yourapp.io/auth/session

The SDK's session helper builds the response in the format the frontend SDKs expect.

For example, using the Express Auth SDK:

app.get('/auth/session', requireWristbandAuth, (req, res) => {
  const sessionResponse = req.session.getSessionResponse({ foo: 'bar' });
  res.status(200).json(sessionResponse);
});

See the Session and Token Endpoint Responses section of Session Management for the response format.

Token Endpoint (Optional)

The Token Endpoint is only needed when your frontend makes API calls directly with the user's access token, rather than routing every call through your backend server. Wristband frontend SDKs call the Token Endpoint to retrieve the current access token and its expiration time. For example:

GET https://customer01.yourapp.io/auth/token

The SDK's session helper builds the response in the format the frontend SDKs expect.

For example, using the Express Auth SDK:

app.get('/auth/token', requireWristbandAuth, (req, res) => {
  const tokenResponse = req.session.getTokenResponse();
  res.status(200).json(tokenResponse);
});