Next.js

What you’ll build

A Next.js API route that requires a valid API key on every request. Invalid or missing keys get rejected with a 401. Time to complete: ~5 minutes

Prerequisites

Unkey account (free)
Keyspace created in your Unkey dashboard

Create a Next.js app

Skip this if you have an existing project.

npx create-next-app@latest my-api
cd my-api

pnpm create next-app@latest my-api
cd my-api

bunx create-next-app my-api
cd my-api

Install the Unkey SDK

npm install @unkey/nextjs

pnpm add @unkey/nextjs

bun add @unkey/nextjs

Add your root key

Get a root key from Settings → Root Keys and add it to your environment:

.env.local

UNKEY_ROOT_KEY="unkey_..."

Never commit your root key. Add .env.local to .gitignore.

Create a protected route

Create a new API route that requires authentication:

app/api/protected/route.ts

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

    // Your API logic here
    //
    // req.unkey.data contains all verification details.
    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! },
);

The withUnkey wrapper handles key extraction, verification, and error responses automatically. Invalid keys never reach your handler.

Start your server

npm run dev

pnpm dev

bun dev

Test it

First, create a test key in your Unkey dashboard, then:

Test with valid key

curl -X POST http://localhost:3000/api/protected \
  -H "Authorization: Bearer YOUR_API_KEY"

You should see:

{
  "message": "Hello!",
  "keyId": "key_..."
}

Now try without a key:

Test without key

curl -X POST http://localhost:3000/api/protected

You’ll get a 401 Unauthorized response.

What’s in `req.unkey`?

After verification, req.unkey.data contains:

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[]?`	Permissions 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)

data.meta is your custom key metadata (set via meta when creating the key). This is different from the response’s top-level meta which contains requestId.

Next steps

Add rate limiting

Limit requests per key

Set usage limits

Cap total requests per key

Add permissions

Fine-grained access control

Next.js SDK Reference

Full SDK documentation

Troubleshooting

Getting 401 even with a valid key?

Ensure the key hasn’t expired or been revoked - Verify the Authorization header format: Bearer YOUR_KEY (note the space) - Check that your root key has the verify_key permission

Environment variable not loading?

Restart your dev server after adding .env.local - Make sure the file is in your project root - Check for typos in the variable name

Getting Started

Platform

Build & Deploy

Networking

Observability

CLI

Security

Keyspaces

AI Code Gen

Audit Logs

CLI

Errors

What you’ll build

Prerequisites

Create a Next.js app

Install the Unkey SDK

Add your root key

Create a protected route

Start your server

Test it

What’s in `req.unkey`?

Next steps

Add rate limiting

Set usage limits

Add permissions

Next.js SDK Reference

Troubleshooting

​What you’ll build

​Prerequisites

Create a Next.js app

Install the Unkey SDK

Add your root key

Create a protected route

Start your server

Test it

​What’s in req.unkey?

​Next steps

Add rate limiting

Set usage limits

Add permissions

Next.js SDK Reference

​Troubleshooting

What you’ll build

Prerequisites

What’s in `req.unkey`?

Next steps

Troubleshooting