Skip to main content

Documentation Index

Fetch the complete documentation index at: https://unkey.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Core Concepts

​
Workspace

A workspace is your top-level account container. Everything in Unkey belongs to a workspace.
  • Can be personal or team-based
  • Contains APIs, keys, identities, rate limit namespaces
  • One owner who can invite members and assign roles
  • Billing is per-workspace

​
API

An API is a container for related API keys. Use APIs to organize keys by:
  • Product: payments-api, analytics-api
  • Environment: production, staging, development
  • Tier: free-tier, pro-tier, enterprise
Each key belongs to exactly one API.

​
API Key

The credential your users include in requests to authenticate with your API. Unkey manages the full lifecycle:
  • Creation: Generate with custom prefix, expiration, limits
  • Verification: Validate and check permissions in ~30ms globally
  • Revocation: Disable or delete when needed
Example: sk_live_abc123...

​
Root Key

A special key that grants access to Unkey’s management API. Use root keys to:
  • Create, update, delete API keys
  • Manage rate limits and permissions
  • Access analytics
Root keys have full access to your workspace. Never expose them in client-side code or public repositories.

​
Key Features

​
Identity

A way to link multiple keys to a single user or entity. Identities let you:
  • Track usage across all of a user’s keys
  • Share rate limits between keys
  • Store user metadata once, not per-key
Use externalId to link to your own user IDs: externalId: "user_123"

​
Credits (Remaining)

Limit how many times a key can be used. Different from rate limiting:
FeatureCreditsRate Limits
Resets?No (unless refill configured)Yes, every window
Use caseTotal quotaRequests per time
Example”1000 requests total""100 requests/minute”
Credits decrement with each verification. When they hit 0, the key is invalid.

​
Refill

Automatically restore credits on a schedule:
  • Daily: Reset at midnight UTC
  • Monthly: Reset on a specific day
Example: “10,000 credits, refills on the 1st of each month”

​
Rate Limit

Restrict requests within a time window. Prevents abuse and ensures fair usage.
  • Limit: Maximum requests allowed
  • Duration: Time window (e.g., 60 seconds)
  • Namespace: Grouping for related limits
Example: “100 requests per minute”

​
Rate Limit Namespace

A container for related rate limits. Namespaces let you:
  • Apply limits across keys or identities
  • Set overrides for specific identifiers
  • Track analytics per namespace
Example namespaces: api-requests, auth-attempts, file-uploads

​
Override

Custom rate limit for a specific identifier. Overrides let you:
  • Give VIP users higher limits
  • Throttle suspicious users
  • Test with elevated limits
Configured in the dashboard — no code changes needed.

​
Permissions & Authorization

​
Permission

A specific action a key can perform. Examples:
  • documents.read
  • documents.write
  • billing.manage
Permissions are checked during verification.

​
Role

A named collection of permissions. Examples:
  • admin → all permissions
  • editor → read + write permissions
  • viewer → read-only permissions
Attach roles to keys instead of individual permissions for easier management.

​
Configuration

​
Prefix

A string prepended to generated keys for identification:
  • sk_live_ → production key
  • sk_test_ → test environment key
  • pk_ → publishable key
Prefixes help users identify key types at a glance.

​
Metadata

Custom JSON data attached to a key. Store anything relevant: 
{
  "environment": "production",
  "plan": "enterprise",
  "customerId": "cust_123"
}
Metadata is returned during verification.

​
External ID

Your identifier for a user or entity. Links Unkey identities to your system:
  • user_123 (your user ID)
  • org_456 (your org ID)
  • team_789 (your team ID)

​
Verification Responses

​
Valid

Key exists and passed all checks (not expired, not disabled, has credits, not rate limited, has required permissions).

​
Code

The reason a verification succeeded or failed:
CodeMeaning
VALIDKey is valid
NOT_FOUNDKey doesn’t exist
EXPIREDKey past expiration date
DISABLEDKey manually disabled
USAGE_EXCEEDEDNo credits remaining
RATE_LIMITEDRate limit exceeded
INSUFFICIENT_PERMISSIONSMissing required permission
FORBIDDENIP whitelist violation

​
Analytics

​
Verification

A single key validation request. Each verification is logged with:
  • Timestamp
  • Key ID
  • Result (valid/invalid + code)
  • Tags (custom dimensions you add)
  • Geographic origin

​
Tags

Custom strings attached to verifications for analytics: 
path=/v1/users
method=POST
version=2024-01
Use tags to segment analytics by endpoint, feature, version, etc.
Last modified on April 7, 2026