Overview

Unkey provides two TypeScript packages:

@unkey/api: Manage keys, APIs, and rate limits (server-side, requires root key)
@unkey/ratelimit: Standalone rate limiting (server-side, requires root key)

For framework-specific wrappers, see @unkey/nextjs and @unkey/hono.

Installation

npm install @unkey/api @unkey/ratelimit

pnpm add @unkey/api @unkey/ratelimit

bun add @unkey/api @unkey/ratelimit

Quick Start

Initialize the client

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

// For key management
const unkey = new Unkey({
  rootKey: process.env.UNKEY_ROOT_KEY!,
});

// For rate limiting
const limiter = new Ratelimit({
  rootKey: process.env.UNKEY_ROOT_KEY!,
  namespace: "my-app",
  limit: 10,
  duration: "60s",
});

Never expose your root key in client-side code. These SDKs are for server-side use only.

Verify an API Key

The most common operation, check if a user’s API key is valid:

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

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

async function handleRequest(request: Request) {
  const apiKey = request.headers.get("x-api-key");

  if (!apiKey) {
    return new Response("Missing API key", { status: 401 });
  }

  try {
    const { meta, data } = await unkey.keys.verifyKey({
      key: apiKey,
    });

    if (!data.valid) {
      // Key is invalid, expired, rate limited, etc.
      return new Response(`Unauthorized: ${data.code}`, { status: 401 });
    }

    // Key is valid, access granted
    // data.identity?.externalId, data.meta, data.credits, etc. available
    return handleAuthenticatedRequest(request, data);
  } catch (err) {
    console.error(err);
    return new Response("Service unavailable", { status: 503 });
  }
}

Verification response

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[]?`	Roles 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)

Check permissions during verification

try {
  const { meta, data } = await unkey.keys.verifyKey({
    key: apiKey,
    permissions: "documents.write", // Required permission
  });

  if (!data.valid && data.code === "INSUFFICIENT_PERMISSIONS") {
    return new Response("Forbidden", { status: 403 });
  }
} catch (err) {
  console.error(err);
  return new Response("Service unavailable", { status: 503 });
}

Create API Keys

Issue new keys for your users:

try {
  const { meta, data } = await unkey.keys.createKey({
    apiId: "api_...",

    // Optional but recommended
    prefix: "sk_live", // Visible prefix
    externalId: "user_123", // Link to your user
    name: "Production key", // Human-readable name

    // Optional limits
    expires: Date.now() + 30 * 24 * 60 * 60 * 1000, // 30 days
    credits: {
      remaining: 1000, // Usage limit
      refill: {
        amount: 1000,
        interval: "monthly", // Auto-refill
      },
    },
    ratelimits: [
      {
        name: "requests",
        limit: 100,
        duration: 60000, // 100/minute
      },
    ],

    // Optional metadata
    meta: {
      plan: "pro",
      createdBy: "admin",
    },
  });

  // Send data.key to your user (only time you'll see the full key!)
  console.log("New key:", data.key);
  console.log("Key ID:", data.keyId);
} catch (err) {
  console.error(err);
  throw new Error("Failed to create key");
}

The full API key is only returned once at creation. Unkey stores only a hash. Make sure to display it to your user immediately.

Update Keys

Modify an existing key’s configuration:

try {
  await unkey.keys.updateKey({
    keyId: "key_...",

    // Any fields you want to change
    name: "Updated name",
    meta: { plan: "enterprise" },
    enabled: true,
    expires: Date.now() + 90 * 24 * 60 * 60 * 1000,
    ratelimits: [
      {
        name: "requests",
        limit: 1000, // Upgraded limit
        duration: 60000,
      },
    ],
  });
} catch (err) {
  console.error(err);
  throw new Error("Failed to update key");
}

Delete Keys

Permanently revoke a key:

try {
  await unkey.keys.deleteKey({
    keyId: "key_...",
  });
} catch (err) {
  console.error(err);
  throw new Error("Failed to delete key");
}

Or disable temporarily (can re-enable later):

try {
  await unkey.keys.updateKey({
    keyId: "key_...",
    enabled: false,
  });
} catch (err) {
  console.error(err);
  throw new Error("Failed to disable key");
}

Rate Limiting

Use @unkey/ratelimit for standalone rate limiting:

import { Ratelimit } from "@unkey/ratelimit";

const limiter = new Ratelimit({
  rootKey: process.env.UNKEY_ROOT_KEY!,
  namespace: "api",
  limit: 100,
  duration: "60s",
});

async function handleRequest(request: Request) {
  const userId = request.headers.get("x-user-id") ?? "anonymous";

  try {
    const { success, remaining, reset } = await limiter.limit(userId);

    if (!success) {
      return new Response("Rate limit exceeded", {
        status: 429,
        headers: {
          "Retry-After": Math.ceil((reset - Date.now()) / 1000).toString(),
          "X-RateLimit-Remaining": "0",
        },
      });
    }

    // Process request...
  } catch (err) {
    console.error(err);
    return new Response("Rate limit service unavailable", { status: 503 });
  }
}

Cost-based rate limiting

Expensive operations can consume more of the limit:

// Normal request costs 1
await limiter.limit(userId);

// Expensive request costs 10
await limiter.limit(userId, { cost: 10 });

Error Handling

Use try/catch to handle errors:

try {
  const { meta, data } = await unkey.keys.createKey({ ... });

  console.log("Request ID:", meta.requestId);
  console.log("Key ID:", data.keyId);
} catch (err) {
  console.error(err);
  throw new Error("Failed to create key");
}

Resilient verification

For production, handle edge cases:

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

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

async function verifyApiKey(key: string): Promise<VerifyResult | null> {
  try {
    const { meta, data } = await unkey.keys.verifyKey({ key });

    return data;
  } catch (err) {
    // Network error, timeout, etc.
    console.error("Unkey verification error:", err);
    return null; // Or return a default allow/deny
  }
}

TypeScript Types

The SDK is fully typed. Import types as needed:

import type { VerifyKeyResult, Key, Api, RatelimitResponse } from "@unkey/api";

Framework Guides

Next.js

withUnkey wrapper for API routes

Hono

Middleware for Hono apps

Express Quickstart

Step-by-step Express guide

Bun Quickstart

Step-by-step Bun guide

Full Reference

GitHub

Complete auto-generated API reference

Official Libraries

Community Libraries

Installation

Quick Start

Initialize the client

Verify an API Key

Verification response

Check permissions during verification

Create API Keys

Update Keys

Delete Keys

Rate Limiting

Cost-based rate limiting

Error Handling

Resilient verification

TypeScript Types

Framework Guides

Next.js

Hono

Express Quickstart

Bun Quickstart

Full Reference

GitHub

​Installation

​Quick Start

​Initialize the client

​Verify an API Key

​Verification response

​Check permissions during verification

​Create API Keys

​Update Keys

​Delete Keys

​Rate Limiting

​Cost-based rate limiting

​Error Handling

​Resilient verification

​TypeScript Types

​Framework Guides

Next.js

Hono

Express Quickstart

Bun Quickstart

​Full Reference

GitHub

Installation

Quick Start

Initialize the client

Verify an API Key

Verification response

Check permissions during verification

Create API Keys

Update Keys

Delete Keys

Rate Limiting

Cost-based rate limiting

Error Handling

Resilient verification

TypeScript Types

Framework Guides

Full Reference