Next.js

Protect your Next.js API routes with Unkey

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)
• API created in your Unkey dashboard

1. Create a Next.js app

   Skip this if you have an existing project.

   npm

   npx create-next-app@latest my-api
   cd my-api
   
2. Install the Unkey SDK

   npm

   npm install @unkey/nextjs
   
3. 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.

4. 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.

5. Start your server

   npm

   npm run dev
   
6. 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