Cloudflare Workers guide

Protect a Cloudflare Worker with API keys. The Worker’s fetch handler calls keys.verifyKey on each request. Store the root key as a Worker secret, never in wrangler.toml.

You need a root key with the permissions listed on this page. Create one in the dashboard under Settings > Root Keys. See Permission reference for every permission.

Create a root key and a keyspace

In the dashboard, go to Settings > Root Keys and create a root key with api.*.create_api, api.*.create_key, and api.*.verify_key. Export it as UNKEY_ROOT_KEY in your shell for the curl commands. You’ll store it as a Worker secret in step 2. 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 and store the root key

@unkey/api (version ) runs on Workers with no polyfills.

npm install @unkey/api
npx wrangler secret put UNKEY_ROOT_KEY

Your code reads it as env.UNKEY_ROOT_KEY. If your Worker also creates keys, add the keyspace ID from step 1 as an UNKEY_API_ID variable in wrangler.toml. It isn’t secret.

Create a key for a user

Create a key 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.Workers have no process.env, so read the secret and keyspace ID from the handler’s env argument.

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";

interface Env {
  UNKEY_ROOT_KEY: string;
  UNKEY_API_ID: string;
}

// Call this from a route your own session check already protects.
export async function issueKey(env: Env, userId: string): Promise<string> {
  const unkey = new Unkey({ rootKey: env.UNKEY_ROOT_KEY });

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

Every field is described in Creating keys.

Verify the key in the fetch handler

env is only available inside the handler, so create the client there. The code below creates it once and reuses it.

src/index.ts

import { Unkey } from "@unkey/api";
import * as errors from "@unkey/api/models/errors";

interface Env {
  UNKEY_ROOT_KEY: string;
}

let unkey: Unkey | undefined;

function client(env: Env): Unkey {
  unkey ??= new Unkey({ rootKey: env.UNKEY_ROOT_KEY });
  return unkey;
}

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;
  }
}

export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    const auth = req.headers.get("authorization") ?? "";
    const key = auth.startsWith("Bearer ") ? auth.slice("Bearer ".length) : "";
    if (!key) {
      return Response.json({ error: "missing API key" }, { status: 401 });
    }

    try {
      const result = await client(env).keys.verifyKey({
        key,
        tags: [`colo=${req.cf?.colo ?? "unknown"}`],
      });
      if (!result.data.valid) {
        return Response.json({ error: result.data.code }, { status: statusFor(result.data.code) });
      }
      return Response.json({ items: [], owner: result.data.identity?.externalId });
    } catch (err) {
      if (err instanceof errors.UnkeyError) {
        console.error("unkey", err.statusCode, err.message);
      }
      return Response.json({ error: "authentication unavailable" }, { status: 503 });
    }
  },
} satisfies ExportedHandler<Env>;

npx wrangler dev
curl http://localhost:8787/ -H "Authorization: Bearer sk_live_..."

Prefer a router? The Hono guide runs unchanged on Workers. Read the root key from c.env.UNKEY_ROOT_KEY instead of process.env.

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`	Client IP not on the keyspace allow list, or 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

Audit logs

Developer portal

Security

Cookbook

Cloudflare Workers guide

Create a root key and a keyspace

Install the SDK and store the root key

Create a key for a user

Verify the key in the fetch handler

Handle the outcome codes

Next steps

Verifying keys

Credits and refill

Cookbook