Express - Unkey Docs

What you'll build#

An Express server with a protected /secret route that requires a valid API key. Requests without a valid key get rejected with a 401.

Time to complete: ~5 minutes

Prerequisites#

Unkey account (free)
Keyspace created in your Unkey dashboard
Node.js 18+

Want to skip ahead?

Clone the complete example and run it locally.

Create your Express app#

mkdir unkey-express && cd unkey-expressnpm init -ynpm install express @unkey/api dotenv

Add your root key#

Get a root key from Settings → Root Keys and create a .env file:

.env

UNKEY_ROOT_KEY="unkey_..."

Warning

Never commit your .env file. Add it to .gitignore.

Create your server#

Create index.js with a protected route:

index.js

const express = require("express");const { Unkey } = require("@unkey/api");require("dotenv").config();const app = express();const port = process.env.PORT || 3000;const unkey = new Unkey({ rootKey: process.env.UNKEY_ROOT_KEY });// Public routeapp.get("/", (req, res) => {  res.json({ message: "Welcome! Try /secret with an API key." });});// Protected routeapp.get("/secret", async (req, res) => {  // 1. Extract the key from the Authorization header  const authHeader = req.headers.authorization;  const key = authHeader?.replace("Bearer ", "");  if (!key) {    return res.status(401).json({ error: "Missing API key" });  }  // 2. Verify with Unkey  try {    const { data } = await unkey.keys.verifyKey({ key });    if (!data.valid) {      // Key is invalid, expired, rate limited, etc.      return res.status(401).json({        error: "Invalid API key",        code: data.code,      });    }    // 3. Key is valid, return protected data    res.json({      message: "Welcome to the secret route!",      keyId: data.keyId,      // Include any metadata you attached to the key      identity: data.identity,    });  } catch (err) {    console.error(err);    return res.status(500).json({ error: "Could not verify key" });  }});app.listen(port, () => {  console.log(`Server running at http://localhost:${port}`);});

Start your server#

node index.js

Test it#

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

Test with valid key

curl http://localhost:3000/secret \  -H "Authorization: Bearer YOUR_API_KEY"

You should see:

{  "message": "Welcome to the secret route!",  "keyId": "key_...",  "identity": null}

Now try without a key:

Test without key

curl http://localhost:3000/secret

You'll get:

{  "error": "Missing API key"}

What's in `data`?#

After successful verification, 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)

Using as middleware#

For cleaner code, extract verification into middleware:

middleware/auth.js

const { Unkey } = require("@unkey/api");const unkey = new Unkey({ rootKey: process.env.UNKEY_ROOT_KEY });async function unkeyAuth(req, res, next) {  const key = req.headers.authorization?.replace("Bearer ", "");  if (!key) {    return res.status(401).json({ error: "Missing API key" });  }  try {    const { data } = await unkey.keys.verifyKey({ key });    if (!data.valid) {      return res.status(401).json({ error: "Invalid API key" });    }    // Attach key info to request for use in route handlers    req.unkey = data;    next();  } catch (err) {    console.error(err);    return res.status(500).json({ error: "Could not verify key" });  }}module.exports = { unkeyAuth };

Then use it on any route:

const { unkeyAuth } = require("./middleware/auth");app.get("/secret", unkeyAuth, (req, res) => {  // req.unkey contains the verification result  res.json({ message: "Secret data", keyId: req.unkey.keyId });});app.get("/another-secret", unkeyAuth, (req, res) => {  res.json({ data: "More protected content" });});

Next steps#

Add rate limiting

Limit requests per key

Set usage limits

Cap total requests per key

Add permissions

Fine-grained access control

SDK Reference

Full TypeScript SDK docs

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

Getting 500 errors?

Check that UNKEY_ROOT_KEY is set correctly in your .env - Make sure you're calling require("dotenv").config() before using env vars - Check the Unkey dashboard for any service issues

TypeScript version?

The code above uses CommonJS. For TypeScript, install types and use imports:

npm install -D typescript @types/express @types/node

import express from "express";import { Unkey } from "@unkey/api";

What you'll build#

Prerequisites#

Create your Express app#

Add your root key#

Create your server#

Start your server#

Test it#

What's in data?#

Using as middleware#

Next steps#

Troubleshooting#

What's in `data`?#