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 |
Create a keyspace
- Navigate to Keyspaces (APIs) in the sidebar.
- Click Create new keyspace.
- 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. |
| IP whitelist | Restrict key verification to specific IP addresses. See IP 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 |
key_space_id and in Sentinel configuration when connecting a keyspace to a deployment.
Each key is composed of a prefix and a random portion:
sk_live_abc123def456ghi789
└─────┘ └──────────────────┘
prefix random (base58-encoded)
Delete a keyspace
Deleting a keyspace permanently removes it and all of its keys. This action cannot be undone.
Delete protection prevents accidental deletion. Disable it in the keyspace
settings before deleting.
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 | Issue, verify, and manage keys |
| Rate limiting | Per-key rate limits |
| Authorization | Roles and permissions |
| Analytics | Query verification data by keyspace |
| Sentinel authentication | Connect keyspaces to Sentinel policies |
