@unkey/nextjs - Unkey Docs

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

github.com/unkeyed/sdks/tree/main/nextjs

Install#

 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: NextRequestWithUnkeyContext) => {    // The key has already been verified at this point    // Access verification details via req.unkey.data    if (!req.unkey.data.valid) {      return new Response("Unauthorized", { status: 401 });    }    // Your API logic here    return Response.json({      message: "Hello!",      keyId: req.unkey.data.keyId,      // If you set an externalId when creating the key:      externalId: req.unkey.data.identity?.externalId,    });  },  { rootKey: process.env.UNKEY_ROOT_KEY! },);

What's in `req.unkey`?#

The req.unkey.data object contains the verification result:

Field	Type	Description
`valid`	`boolean`	Whether the key passed all checks
`code`	`string`	Status code (`VALID`, `NOT_FOUND`, `RATE_LIMITED`, etc.)
`keyId`	`string`	The key's unique identifier
`name`	`string?`	Human-readable name of the key
`meta`	`object?`	Custom metadata associated with the key
`expires`	`number?`	Unix timestamp (in milliseconds) when the key will expire (if set)
`credits`	`number?`	Remaining uses (if usage limits set)
`enabled`	`boolean`	Whether the key is enabled
`roles`	`string[]?`	Roles attached to the key
`permissions`	`string[]?`	Permissions attached to the key
`identity`	`object?`	Identity info if `externalId` was set when creating the key
`ratelimits`	`object[]?`	Rate limit states (if rate limiting configured)

Note

Access these via req.unkey.data.valid, req.unkey.data.keyId, etc.

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) => {    // ...  },  {    rootKey: process.env.UNKEY_ROOT_KEY!,    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) => {    // ...  },  {    rootKey: process.env.UNKEY_ROOT_KEY!,    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) => {    // ...  },  {    rootKey: process.env.UNKEY_ROOT_KEY!,    handleInvalidKey: (req, res) => {      return new Response("Unauthorized", { status: 401 });    },  },);

Install#

What's in req.unkey?#

getKey#

onError#

handleInvalidKey#

What's in `req.unkey`?#

`getKey`#

`onError`#

`handleInvalidKey`#