Express guide

Protect Express routes with API keys. A middleware reads the bearer token, calls keys.verifyKey, rejects bad keys with the right status, and puts the result on res.locals.unkey for your handlers.

Create a root key with the permissions listed on this page under Root Keys in the dashboard sidebar. CLI commands can instead use a session from unkey login with the required permissions. See Permission reference for every permission.

Create a root key and a keyspace

Open Root Keys in the dashboard sidebar and create a root key with api.*.create_api, api.*.create_key, and api.*.verify_key. Put it in your server’s UNKEY_ROOT_KEY environment variable. Never send it to a browser or mobile app.Then create a keyspace, which holds your keys. Use Keyspaces (APIs) in the dashboard, or apis.createApi:

create a keyspace

curl -X POST https://api.unkey.com/v2/apis.createApi \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-api" }'

Keep the data.apiId from the response. You need it to create keys. See Root keys for more on root keys.

Install the SDK

@unkey/api (version ) is the client for the whole API.

npm install @unkey/api express

pnpm add @unkey/api express

Create a key for a user

Create a key from your backend when a user signs up or asks for one. externalId links the key to the user, so verification tells you who’s calling. meta comes back on every verification. You get data.key only once: show it to the user and store only data.keyId.

curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "apiId": "api_...", "prefix": "sk_live", "externalId": "user_123", "meta": { "plan": "free" } }'

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

const unkey = new Unkey({ rootKey: process.env.UNKEY_ROOT_KEY ?? "" });

const created = await unkey.keys.createKey({
  apiId: process.env.UNKEY_API_ID ?? "",
  prefix: "sk_live",
  externalId: "user_123",
  meta: { plan: "free" },
});
// created.data.key is the plaintext, created.data.keyId the handle you keep

Every field is described in Creating keys.

Verify the key in a middleware

The middleware the key once per request and puts the result on res.locals.unkey. Routes that need extra permissions pass a permissions query.Keep next() outside the try. Otherwise an error in a route handler is caught here and answered as a 503 authentication failure.

src/unkey.ts

import { Unkey } from "@unkey/api";
import * as errors from "@unkey/api/models/errors";
import type { V2KeysVerifyKeyResponseBody } from "@unkey/api/models/components";
import type { NextFunction, Request, Response } from "express";

const unkey = new Unkey({ rootKey: process.env.UNKEY_ROOT_KEY ?? "" });

export function requireKey(permissions?: string) {
  return async (req: Request, res: Response, next: NextFunction) => {
    const auth = req.header("authorization") ?? "";
    const key = auth.startsWith("Bearer ") ? auth.slice("Bearer ".length) : "";
    if (!key) {
      return res.status(401).json({ error: "missing API key" });
    }

    let result: V2KeysVerifyKeyResponseBody;
    try {
      result = await unkey.keys.verifyKey({
        key,
        permissions,
        tags: [`endpoint=${req.path}`, `method=${req.method}`],
      });
    } catch (err) {
      if (err instanceof errors.UnkeyError) {
        console.error("unkey", err.statusCode, err.message);
      }
      return res.status(503).json({ error: "authentication unavailable" });
    }

    if (!result.data.valid) {
      return res.status(statusFor(result.data.code)).json({ error: result.data.code });
    }
    res.locals.unkey = result.data;
    next();
  };
}

function statusFor(code: string): number {
  switch (code) {
    case "RATE_LIMITED":
      return 429;
    case "USAGE_EXCEEDED":
      return 402;
    case "FORBIDDEN":
    case "INSUFFICIENT_PERMISSIONS":
      return 403;
    default:
      return 401;
  }
}

src/server.ts

import express from "express";
import { requireKey } from "./unkey";

const app = express();

app.get("/items", requireKey(), (_req, res) => {
  res.json({ items: [], owner: res.locals.unkey.identity?.externalId });
});

app.post("/items", requireKey("items.write"), (_req, res) => {
  res.status(201).json({ ok: true });
});

app.listen(3000);

curl http://localhost:3000/items -H "Authorization: Bearer sk_live_..."

Handle the outcome codes

keys.verifyKey returns HTTP 200 for every outcome. Check data.valid, then data.code for the reason, and return the matching status from your API:

`data.code`	Meaning	Return
`VALID`	Every check passed.	continue
`NOT_FOUND`	No such key, or your root key may not verify this keyspace.	401
`DISABLED`	The key was disabled.	401
`EXPIRED`	The key’s expiry passed.	401
`FORBIDDEN`	The workspace is disabled.	403
`INSUFFICIENT_PERMISSIONS`	The `permissions` query was not satisfied.	403
`RATE_LIMITED`	A on the key or its identity was exceeded.	429
`USAGE_EXCEEDED`	The key has no credits left.	402 or 429

Remaining credits are in data.credits, and each checked rate limit is in data.ratelimits with remaining and reset. The call only fails with an HTTP error (which the SDKs throw) when the call itself is wrong, such as a bad root key or a malformed body. See Verifying keys for every field.

Next steps

Verifying keys

Every request field, the order of checks, and every response field.

Credits and refill

Meter usage per key and refill balances on a schedule.

Cookbook

Copy-ready recipes for rate limits, billing, and subscription tiers.

Get started

Framework guides

Keyspaces

Keys

Rate limiting

Identities

Authorization

Analytics

Developer portal

Security

Cookbook

Create a root key and a keyspace

Install the SDK

Create a key for a user

Verify the key in a middleware

Handle the outcome codes

Next steps

Verifying keys

Credits and refill

Cookbook