Next.js - Unkey Docs

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-apicd my-api

Install the Unkey SDK#

npm install @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_..."

Warning

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! },);

Tip

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

Start your server#

npm run 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)

Note

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

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#

Troubleshooting#

What's in `req.unkey`?#