Keyspaces

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:

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.

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

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

Getting Started

Platform

Build & Deploy

Networking

Observability

CLI

Security

AI Code Gen

Audit Logs

CLI

Errors

Keyspaces

When to create separate keyspaces

Create a keyspace

Keyspace settings

Identifiers

Storage and validation

Key format

Delete a keyspace

Constraints

​When to create separate keyspaces

​Create a keyspace

​Keyspace settings

​Identifiers

​Storage and validation

​Key format

​Delete a keyspace

​Constraints

​Related pages

When to create separate keyspaces

Create a keyspace

Keyspace settings

Identifiers

Storage and validation

Key format

Delete a keyspace

Constraints

Related pages