# 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
{
  "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
path=/v1/users
method=POST
version=2024-01
```

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