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

# Keyspaces

> A keyspace in Unkey groups related keys, configuration, and analytics. Learn how to create and manage keyspaces within your workspace.

A keyspace is a container for related API keys. It doesn't represent a running service or HTTP endpoint. Instead, it provides a boundary for organizing keys by product, environment, or tier. In the dashboard, keyspaces appear under **Keyspaces (APIs)**.

Every key belongs to exactly one keyspace. When you create a key, you specify which keyspace it belongs to by passing its `apiId`.

## When to create separate keyspaces

Use multiple keyspaces when you need independent key prefixes, permissions, or analytics boundaries.

| Strategy       | Example names                | Why                                                    |
| -------------- | ---------------------------- | ------------------------------------------------------ |
| By product     | `payments-api`, `search-api` | Different key prefixes and permission sets per product |
| By environment | `production`, `staging`      | Separate keys and usage tracking per stage             |
| By tier        | `free-tier`, `enterprise`    | Different default rate limits per plan                 |

A single keyspace works fine if all your keys share the same configuration and you filter by metadata or tags instead.

## Create a keyspace

1. Navigate to **Keyspaces (APIs)** in the sidebar.
2. Click **Create new keyspace**.
3. Enter a name for your keyspace.

Unkey generates a unique **API ID** (`api_xxx`) for the keyspace. This is the identifier you pass when creating keys and querying analytics, so keep it handy.

## Keyspace settings

Each keyspace exposes configuration through its settings page.

| Setting              | Description                                                                                                                              |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Name                 | Human-readable label shown in the dashboard                                                                                              |
| Default prefix       | Prefix prepended to every key created in this keyspace (for example, `sk_live`)                                                          |
| Default bytes        | Number of random bytes used to generate new keys (default: 16)                                                                           |
| Store encrypted keys | When enabled, Unkey stores an encrypted copy of each key so it can be recovered later. See [Recovering keys](/security/recovering-keys). |
| IP whitelist         | Restrict key verification to specific IP addresses. See [IP whitelist](/platform/apis/features/whitelist).                               |

## Identifiers

Each keyspace has two identifiers:

| Identifier  | Format    | Used for                                                                |
| ----------- | --------- | ----------------------------------------------------------------------- |
| API ID      | `api_xxx` | Creating keys and most API calls — the identifier you'll use most often |
| KeySpace ID | `ks_xxx`  | Analytics queries (as `key_space_id`) and Sentinel configuration        |

## Storage and validation

A keyspace is the storage and validation boundary for all of its keys (internally, it's backed by a `key_auth` record). When Sentinel or the verification endpoint receives a key, it resolves the keyspace by key prefix and validates the key against that keyspace's configuration.

The keyspace stores:

| Property               | Description                                                                                            |
| ---------------------- | ------------------------------------------------------------------------------------------------------ |
| `id`                   | Unique identifier (`ks_xxx`), used in Sentinel policies and analytics queries                          |
| `default_prefix`       | Prefix for new keys (for example, `sk_live`). The prefix appears before the random portion of the key. |
| `default_bytes`        | Number of random bytes per key (default: 16, producing a 24-character base58 string)                   |
| `store_encrypted_keys` | Whether to store a recoverable encrypted copy of each key                                              |
| `size_approx`          | Approximate number of live keys in this keyspace                                                       |

KeySpace IDs appear in analytics queries as `key_space_id` and in Sentinel configuration when connecting a keyspace to a deployment.

### Key format

Each key is composed of a prefix and a random portion:

```text theme={"theme":"kanagawa-wave"}
sk_live_abc123def456ghi789
└─────┘ └──────────────────┘
 prefix   random (base58-encoded)
```

The prefix is optional but recommended. It makes keys visually identifiable and lets Unkey route verification requests to the correct keyspace without a database lookup.

## Delete a keyspace

Deleting a keyspace permanently removes it and all of its keys. This action cannot be undone.

<Warning>
  Delete protection prevents accidental deletion. Disable it in the keyspace
  settings before deleting.
</Warning>

## Constraints

| Limit                   | Value          |
| ----------------------- | -------------- |
| Keyspaces per workspace | Varies by plan |
| Key prefix max length   | 8 characters   |
| Default bytes range     | 16 to 32       |

## Related pages

| Page                                                                | Description                            |
| ------------------------------------------------------------------- | -------------------------------------- |
| [API keys](/platform/apis/introduction)                             | Issue, verify, and manage keys         |
| [Rate limiting](/platform/apis/features/ratelimiting/overview)      | Per-key rate limits                    |
| [Authorization](/platform/apis/features/authorization/introduction) | Roles and permissions                  |
| [Analytics](/platform/analytics/overview)                           | Query verification data by keyspace    |
| [Sentinel authentication](/platform/sentinel/authentication)        | Connect keyspaces to Sentinel policies |