Skip to main content
Create a keyspace, issue a key with keys.createKey, and it with keys.verifyKey. Both are HTTPS calls to api.unkey.com, so they work from any language or host. Already storing keys yourself? Migrating keys imports your existing hashes so users keep the same keys.

​
Initial Setup

Do these once in the dashboard before you write any code.
1

Create a root key

Your backend calls the Unkey API with a root key. Open Root Keys in the dashboard sidebar, click New Root Key, and name it, for example quickstart. You need the workspace admin role to see Root Keys.
New Root Key panel with quickstart entered as the name and the permission templates below
Under Permissions, select the Verify keys template.
New Root Key panel with the Verify keys permission template highlighted
Click the policy to expand it, then select Write on the Keys row so the root key can also create keys. Click Create key.
Expanded Verify keys policy with Write and Verify selected on the Keys row and the Create key button
Copy the secret and store it as UNKEY_ROOT_KEY.
Unkey shows the root key only once. If you close the dialog without copying it, rotate the key or create a new one.
2

Create a keyspace

A keyspace holds the keys for one product, environment, or tier. In the dashboard, open Keyspaces (APIs), click Create keyspace, and name it.
Create keyspace dialog with a name entered and the Create Keyspace button
Copy the API ID (api_...) from its settings page. You will need this ID to create keys.
Keyspace settings page with the API ID field highlighted

​
Key Actions

Use the language switcher to change the code samples.
1

Create a key

Call keys.createKey with the API ID. name is an internal label your users never see.
data.key is shown only once. Copy it now and give it to your user.
2

Verify the key

Run this on every incoming request. You don’t pass an apiId because the key identifies its keyspace.

​
Reading the verification response

Verification returns HTTP 200 even when the key is rejected. Check data.valid. When it’s false, data.code says why.
Fields such as credits, ratelimits, meta, and identity appear once you configure them on the key. Verifying keys lists every field and code value.

​
Next steps

Creating keys

Prefixes, expiry, credits, rate limits, permissions, and metadata on one key.

Verifying keys

The order of checks, the code enum, and caching behavior.

Credits and refill

Sell a fixed number of requests and refill them on a schedule.

Keyspaces, keys, identities, and root keys

How the objects you just used fit together.
Last modified on October 30, 2026