Skip to main content
API Management issues API keys to your users and checks them on every request. You work with four objects:
  • Keyspace: groups related keys.
  • Key: the credential your user sends you.
  • Identity: ties several keys to one user or organization.
  • Root key: the credential you send to Unkey.
Credits, rate limits, permissions, and analytics are all settings on, or views of, these four.

Keyspace

A keyspace holds related keys. You might create one per product, per such as production and staging, or per pricing tier. Every key belongs to exactly one keyspace. When you create a key, you name its keyspace by its API ID (api_...), which you’ll find on the keyspace’s settings page.
Keyspace settings page with the API ID field highlighted
A keyspace also sets defaults for new keys, such as a prefix and key length. Keyspaces explains when to create more than one.

Key

A key is a random string, with an optional prefix, that you give to your user. Unkey stores only a hash of it unless recoverable keys have been enabled. On every request, your backend sends the key to keys.verifyKey, and Unkey runs the checks set on it.
Create key dialog with tabs for General Setup, Ratelimit, Credits, Expiration, Permissions, and Metadata
Every check is optional: whether the key is enabled, when it expires, how many credits it has left, which rate limits apply, and which permissions and roles it has. A key can also carry JSON metadata that comes back on every verification, so your backend can read a plan tier or feature flag without its own database lookup. Creating keys lists every field.

Identity

An identity represents one user, organization, or service account in your system, named by an externalId you choose. Keys linked to the same identity share its rate limits and metadata. When you pass externalId to keys.createKey, Unkey creates the identity if it doesn’t exist and links the key to it, so most apps never call the identity endpoints directly. Identities covers this in detail.
Identity page with its verification chart and logs

Root key

A root key authenticates you, not your users. Every call to api.unkey.com sends a root key in the Authorization: Bearer header, and its permissions decide which calls succeed. Workspace admins create root keys from Root Keys in the dashboard sidebar. Root keys covers granting permissions and rotating keys.
Root Keys page listing root keys with their permissionsRoot Keys page listing root keys with their permissions

How the objects relate

Each request from your user involves two keys: their key, which they send to you, and your root key, which you send to Unkey to verify theirs. Your user’s key can’t call the Unkey API, and your root key should never leave your servers.

Next steps

Issue and verify your first key

Put the four objects to work in a few minutes.

Keyspaces

Decide how many keyspaces you need and what they store.
Last modified on October 29, 2026