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#
- Navigate to Keyspaces (APIs) in the sidebar.
- Click 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, range: 16 to 255) |
| 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 gateway 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 the gateway 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 gateway 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, range: 16 to 255) |
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 gateway configuration when connecting a keyspace to a deployment.
Key format#
Each key is composed of a prefix and a random portion:
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.
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 255 |
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 |
| Gateway authentication | Connect keyspaces to gateway policies |