@unkey/nextjs

The official Next.js SDK for Unkey. Use this within your route handlers as a simple, type-safe way to verify API keys.

​

Install

• npm
• pnpm
• yarn
• bun

 npm install @unkey/nextjs

Protecting API routes is as simple as wrapping them with the withUnkey handler:

import { NextRequestWithUnkeyContext, withUnkey } from '@unkey/nextjs';

export const POST = withUnkey(async (req) => {

  // Process the request here
  // You have access to the verification response using `req.unkey`
  console.log(req.unkey);
  
  return new Response('Your API key is valid!');
});

That’s it! Since this is just handling key verification, there’s no need to specify a root key as an environment variable.

If you want to customize how withUnkey processes incoming requests, you can do so as follows:

​

getKey

By default, withUnkey will look for a bearer token located in the authorization header. If you want to customize this, you can do so by passing a getter in the configuration object:

export const GET = withUnkey(async (req) => {
  // ...
}, {
	getKey: (req) => new URL(req.url).searchParams.get("key"),
});

​

onError

You can specify custom error handling. By default errors will be logged to the console, and withUnkey will return a NextResponse with status 500.

export const GET = withUnkey(async (req) => {
  // ...
}, {
	onError: async (req, res) => {
      await analytics.trackEvent(`Error ${res.code}: ${res.message}`)
      return new NextResponse("Unkey error", { status: 500 })
    }
});

​

handleInvalidKey

Specify what to do if Unkey reports that your key is invalid.

export const GET = withUnkey(async (req) => {
  // ...
}, {
	handleInvalidKey: (req, res) => {
      return new Response("Unauthorized", { status: 401 })
    }
});

​

Disable telemetry

By default, Unkey collects anonymous telemetry data to help us understand how our SDKs are used.

If you wish to disable this, you can do so by passing a boolean flag to the constructor:

export const GET = withUnkey(async (req) => {
  // ...
}, { disableTelemetry: true });