Glossary

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 keyspaces, keys, identities, rate limit namespaces
• One owner who can invite members and assign roles
• Billing is per-workspace

Keyspace#

A keyspace is a container for related API keys. Use keyspaces 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 keyspace.

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

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:

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:

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/usersmethod=POSTversion=2024-01

Use tags to segment analytics by endpoint, feature, version, etc.