API Keys - Unkey Docs

API keys are the most common way to authenticate requests to your API. Unkey handles the entire lifecycle, creating keys, verifying them on every request, tracking usage, and revoking them when needed, so you can focus on your actual API logic.

When to use API keys#

API keys work best when you need:

Machine-to-machine authentication: Backend services, scripts, or integrations calling your API
Usage tracking per customer: Know who's making requests and how many
Simple integration: A single header (Authorization: Bearer sk_...) that developers understand
Granular control: Per-key rate limits, expiration, and permissions

Note

For user-facing authentication (login flows, sessions), you'll typically use OAuth, JWTs, or an auth provider like Clerk or Auth0 alongside Unkey. Unkey handles the API key layer, not user sessions.

How it works#

Create a keyspace in Unkey

A keyspace in Unkey is a container for keys. You might have separate keyspaces for "Production" and "Staging", or for different products.

Issue keys to users

When a user signs up or requests API access, create a key for them. You can attach metadata (user ID, plan tier), set limits, and configure expiration.

Verify on every request

When a request hits your API, extract the key from the header and verify it with Unkey. We'll tell you if it's valid, who it belongs to, and how many requests they have left.

Manage the lifecycle

Revoke keys when users churn. Rotate keys when security requires it. Update limits when users upgrade. All through the dashboard or API.

Quick example#

Here's what verification looks like in practice:

import { Unkey } from "@unkey/api";const unkey = new Unkey({ rootKey: process.env.UNKEY_ROOT_KEY! });export async function handler(req: Request) {  // 1. Extract the key from the Authorization header  const key = req.headers.get("Authorization")?.replace("Bearer ", "");  if (!key) {    return new Response("Missing API key", { status: 401 });  }  try {    // 2. Verify with Unkey    const { meta, data } = await unkey.keys.verifyKey({ key });    if (!data.valid) {      // Key is invalid, expired, rate limited, or has no remaining uses      return new Response("Unauthorized", { status: 401 });    }    // Continue with your API logic...    return new Response("Hello!");  } catch (err) {    console.error(err);    return new Response("Service unavailable", { status: 503 });  }}

What you get with each verification#

When you verify a key, Unkey returns:

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)

Features#

Unkey keys support much more than basic authentication:

Rate limiting

Limit requests per key, per second, minute, hour, or any window.

Usage limits

Cap total requests per key. Perfect for API credits or trial limits.

Auto-refill

Automatically restore usage limits on a schedule (daily, monthly, etc).

Expiration

Create keys that automatically expire after a set time.

Permissions

Attach roles and permissions for fine-grained access control.

Analytics

See usage patterns, top consumers, and verification trends.

Next steps#

Quickstart: API Keys

Full walkthrough for Next.js, Bun, Express, or Hono.

API Reference

All endpoints for creating, updating, and managing keys.