Add Auth Endpoints

Learn how to create the necessary auth endpoints needed to integrate your application with Wristband.

To implement login and logout flows with Wristband, you'll need to use the Wristband SDK to create three endpoints in your application: the Login Endpoint, the Callback Endpoint, and the Logout Endpoint.


Login Endpoint

The Login Endpoint is responsible for initiating login requests to Wristband. The code within the Login Endpoint constructs the Wristband authorization request and then redirects to Wristband's Authorize Endpoint. After redirecting to Wristband's Authorize Endpoint, the user will then land on Wristband's hosted login page; there, they can complete the login process.

The URL of your Login Endpoint must match the login URL you configured when you created your Wristband Application. It must also match the loginUrl value of your SDK configuration.

//
// Location -> src/pages/api/auth/login.ts
// 
// The Login Endpoint path can be any value you prefer, but it must match 
// your Wristband application's configured login URL path and the SDK loginUrl path.
//
import type { NextApiRequest, NextApiResponse } from 'next';
import { wristbandAuth } from '@/wristband-auth';

export default async function handleLogin(req: NextApiRequest, res: NextApiResponse) {
  try {
    // Call the Wristband login() method which will redirect to Wristband's
    // hosted login page.
    await wristbandAuth.pageRouter.login(req, res);
  } catch (error) {
    console.error(error);
    return res.status(500).json({ error: "Internal Server Error" });
  }
}

//
// Location -> src/app/api/auth/login/route.ts
//
// The Login Endpoint path can be any value you prefer, but it must match 
// your Wristband application's configured login URL path and the SDK loginUrl path.
//
import type { NextRequest } from 'next/server';
import { wristbandAuth } from '@/wristband-auth';

export async function GET(req: NextRequest) {
  try {
    // Call the Wristband login() method which will redirect to Wristband's hosted login page.
    return await wristbandAuth.appRouter.login(req); 
  } catch (error) {
    console.error(error);
    return Response.json({ error: "Internal Server Error" }, { status: 500 });
  }
}

For more details about the Login Endpoint implementation, review our Login Endpoint documentation.




Callback Endpoint

After a user authenticates, Wristband will redirect back to your application's Callback Endpoint. The Callback Endpoint should then verify that the user successfully authenticated. If the user has successfully authenticated, you can retrieve their tokens and claims before redirecting back to your application's home page or an explicit return URL.

The URL of your Callback Endpoint must match the callback URL you configured when you created your Wristband OAuth2 Client. It must also match the redirectUri value of your SDK configuration

//
// Location -> src/pages/api/auth/callback.ts
//
// The Callback Endpoint path can be any value you prefer, but it must match 
// the path of your OAuth2 Client callback URL and the SDK redirectUri path.
//
import type { NextApiRequest, NextApiResponse } from 'next';
import { wristbandAuth } from '@/wristband-auth';
import { CallbackResultType, PageRouterCallbackResult } from '@wristband/nextjs-auth';

export default async function handleCallback(req: NextApiRequest, res: NextApiResponse) {
  try {
    // 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: PageRouterCallbackResult = await wristbandAuth.pageRouter.callback(req, res);
    const { callbackData, result } = callbackResult;

    // For some edge cases, such as if an invalid grant was passed to the token API,
    // the SDK will require a redirect to restart the login flow.  The SDK will have
    // already invoked the redirect() function, so we just stop execution by
    // returning.
    if (result === CallbackResultType.REDIRECT_REQUIRED) {
      return;
    }
    
    //
    // Typically, this is where you would create your session and add CSRF handling,
    // however, we'll ignore those topics for now, as they will be covered in more
    // detail later in this guide. 
    //

    // 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>');
  } catch (error) {
    console.error(error);
    return res.status(500).json({ error: "Internal Server Error" });
  }
}

//
// Location -> src/app/api/auth/callback/route.ts
// 
// The Callback Endpoint path can be any value you prefer, but it must match 
// the path of your OAuth2 Client callback URL and the SDK redirectUri path.
//
import { NextRequest } from 'next/server';
import { AppRouterCallbackResult, CallbackResultType } from '@wristband/nextjs-auth';
import { wristbandAuth } from '@/wristband-auth';

export async function GET(req: NextRequest) {
  try {
    // 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: AppRouterCallbackResult = await wristbandAuth.appRouter.callback(req);
    const { callbackData, redirectResponse, result } = callbackResult;

    // For some edge cases, such as if an invalid grant was passed to the token API,
    // the SDK will require a redirect to restart the login flow.  The SDK will provide
    // an already created NextResponse that will perform a redirect. Your application must
    // return this response in this scenario.
    if (result === CallbackResultType.REDIRECT_REQUIRED) {
      return redirectResponse;
    }

    //
    // Typically, this is where you would create your session and add CSRF handling,
    // however, we'll ignore those topics for now, as they will be covered in more
    // detail later in this guide. 
    //

    // Once the Callback Endpoint has completed,  we create a NextResponse that will 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.
    const appUrl = callbackData!.returnUrl || '<replace_with_a_default_return_url>';
    const callbackResponse = await wristbandAuth.appRouter.createCallbackResponse(req, appUrl);
    return callbackResponse;
  } catch (error) {
    console.error(error);
    return Response.json({ error: "Internal Server Error" }, { status: 500 });
  }
}

For more details about the Callback Endpoint implementation, review our Callback Endpoint documentation.




Logout Endpoint

The Logout Endpoint is responsible for cleaning up any session data and tokens associated with your authenticated user. Your Logout Endpoint path can be any value you want.

//
// Location -> src/pages/api/auth/logout.ts
//
import type { NextApiRequest, NextApiResponse } from 'next';
import { wristbandAuth } from '@/wristband-auth';

export default async function handleLogout(req: NextApiRequest, res: NextApiResponse) {
  try {
    //
    // Typically, this is where you would delete state such as session and CSRF
    // cookies. However, we'll ignore those topics for now, as they will be 
    // covered in more detail later in this guide. 
    //
    
    // Call the Wristband logout() method which 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.
    return await wristbandAuth.pageRouter.logout(req, res);
  } catch (error) {
    console.error(error);
    return res.status(500).json({ error: "Internal Server Error" });
  }
}

//
// Location -> src/app/api/auth/logout/route.ts
//
import type { NextRequest } from 'next/server';
import { wristbandAuth } from '@/wristband-auth';

// Logout endpoint
export async function GET(req: NextRequest) {
  try {
    //
    // Typically, this is where you would delete state such as session and CSRF
    // cookies. However, we'll ignore those topics for now, as they will be 
    // covered in more detail later in this guide. 
    //
    
    // Call the Wristband logout() method which 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.
    return await wristbandAuth.appRouter.logout(req);
  } catch (error) {
    console.error(error);
    return Response.json({ error: "Internal Server Error" }, { status: 500 });
  }
}

For more details about the Logout Endpoint implementation, review our Logout Endpoint documentation.


What’s Next

Next, let's test that your application can successfully redirect to Wristband's hosted login page.