> ## 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.

# Glossary

> Definitions of key terms and concepts used throughout the Unkey platform including workspaces, keyspaces, keys, identities, rate limiting, and root keys.

## 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

<Warning>
  Root keys have full access to your workspace. Never expose them in client-side
  code or public repositories.
</Warning>

## 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" |

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:

```json theme={"theme":"kanagawa-wave"}
{
  "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:

| 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

### Tags

Custom strings attached to verifications for analytics:

```text theme={"theme":"kanagawa-wave"}
path=/v1/users
method=POST
version=2024-01
```

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