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:
| Feature | Credits | Rate Limits |
|---|
| Resets? | No (unless refill configured) | Yes, every window |
| Use case | Total quota | Requests per time |
| Example | ”1000 requests total" | "100 requests/minute” |
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.readdocuments.writebilling.manage
Permissions are checked during verification.
Role
A named collection of permissions. Examples:
admin → all permissionseditor → read + write permissionsviewer → 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 keysk_test_ → test environment keypk_ → publishable key
Prefixes help users identify key types at a glance.
Custom JSON data attached to a key. Store anything relevant:
{
"environment": "production",
"plan": "enterprise",
"customerId": "cust_123"
}
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:
| Code | Meaning |
|---|
VALID | Key is valid |
NOT_FOUND | Key doesn’t exist |
EXPIRED | Key past expiration date |
DISABLED | Key manually disabled |
USAGE_EXCEEDED | No credits remaining |
RATE_LIMITED | Rate limit exceeded |
INSUFFICIENT_PERMISSIONS | Missing required permission |
FORBIDDEN | IP 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
Custom strings attached to verifications for analytics:
path=/v1/users
method=POST
version=2024-01
