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
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
1
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.
2
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.
3
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.
4
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:What you get with each verification
When you verify a key, Unkey returns: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.