Overview - Unkey Docs

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

Quick Start#

Initialize the client#

import { Unkey } from "@unkey/api";import { Ratelimit } from "@unkey/ratelimit";// For key managementconst unkey = new Unkey({  rootKey: process.env.UNKEY_ROOT_KEY!,});// For rate limitingconst limiter = new Ratelimit({  rootKey: process.env.UNKEY_ROOT_KEY!,  namespace: "my-app",  limit: 10,  duration: "60s",});

Warning

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

Warning

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 1await limiter.limit(userId);// Expensive request costs 10await 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