NextJS
Learn more about using Oneloop NextJS SDK
This SDK is for adding authentication to your NextJS routes. If you would like to add our embeddable frontend UI to your NextJS app, please refer to the Oneloop UI SDK.
Our NextJS SDK is a simple way to add authentication to your NextJS routes. We have also written an in-depth blog on how to add API Keys to your NextJS routes using Oneloop. You can read it here.
Installation
npm i @oneloop-hq/nextjs@latest
Adding Authentication
Adding Oneloop auth to your NextJS routes is as simple as adding the auth
higher order function to your route handler.
First you create a oneloop client using ‘createOneloop’ function and pass in your Oneloop SDK key to it.
Then you pass this client to the auth
higher order function.
This function will automatically verify the user’s API key and return a 401 if the key is invalid. To override this behavior, you can pass in a custom error handlers as the third argument as shown here
Please make sure not to expose your Oneloop SDK key in your frontend code. Always add your SDK key to your server components or environment variables.
"use server";
import { createOneloop } from "@oneloop-hq/nextjs";
const oneloop = createOneloop("<YOUR_ONELOOP_SDK_KEY>");
export const GET = oneloop.auth(async (request: Request) => {
return new Response("Profile Endpoint Authenticated");
});
Validating with scopes
At Oneloop, we call RBAC / Permissions as Scopes. You can easily add scopes to your route by passing in the scopes
property to the auth
function.
Scopes takes in an array of objects with the representation
and optional read
, create
, update
, and del
properties.
So to check if the key has read and create access attached to profile scope, we can modify our code as below
export const GET = oneloop.auth(
async (request: Request) => {
return new Response("Profile Endpoint Authenticated");
},
{
scopes: [
{
representation: "profile",
read: true,
create: true,
},
],
}
);
Handling Errors
You can also pass in a custom handlers in econd argument to the auth
function for handling errors and invalid keys.
There are 2 types of handlers you can pass in: onError
and onInvalidKey
.
onInvalidKey()
This function will be called if the user’s API key is invalid, rate limited, reached usage limit, or does not have the required scopes
export const GET = oneloop.auth(
async (request: Request) => {
return new Response("Profile Endpoint Authenticated");
},
{
scopes: [
{
representation: "profile",
read: true,
create: true,
},
],
onInvalidKey: async (request, error) => {
return new Response("Invalid Key: " + err.message, { status: err.code });
},
}
);
onError()
This function will be called if there is an error while verifying the user’s API key. Possible scenario can be if you passed in the wrong Oneloop SDK Key
export const GET = oneloop.auth(
async (request: Request) => {
return new Response("Profile Endpoint Authenticated");
},
{
scopes: [
{
representation: "profile",
read: true,
create: true,
},
],
onError: async (request, error) => {
return new Response("Error while verifying API key", { status: 500 });
},
}
);