Issue and verify your first key

Create a keyspace, issue a key, and it from your backend. Every step is an HTTPS call to api.unkey.com, so it works from any host or language.

You need a root key with the permissions listed on this page. Create one in the dashboard under Settings > Root Keys, and pass it as Authorization: Bearer <root key>. See Permission reference for every permission.

The root key you create needs api.*.create_key and api.*.verify_key. Pick your language with the switcher. Only the steps that call the API change.

Create a keyspace

A keyspace holds the keys for one product, environment, or tier. In the dashboard, open Keyspaces (APIs) in the sidebar, click Create keyspace, and give it a name. Copy the API ID (api_...) from its settings page. You pass it when you create keys.

Create keyspace dialog with a name entered and the Create Keyspace button

Create a key

Call keys.createKey with the API ID. The name is only for you. Your users never see it.

curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "api_...",
    "name": "My first key"
  }'

This is the only time you see the key. Copy data.key now and give it to your user.

{
  "meta": { "requestId": "req_..." },
  "data": {
    "keyId": "key_...",
    "key": "..."
  }
}

Verify the key

This is the call your backend makes on every incoming request. There’s no apiId field because the key alone identifies its keyspace.

curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "key": "<the key from the previous step>" }'

How you read the verification response

Verification returns HTTP 200 even when the key is rejected. data.valid tells you whether the key passed. When it didn’t, data.code says why.

{
  "meta": { "requestId": "req_..." },
  "data": {
    "valid": true,
    "code": "VALID",
    "keyId": "key_...",
    "name": "My first key",
    "enabled": true
  }
}

The response gets more fields as you set more on the key, such as credits, ratelimits, meta, and identity. Verifying keys lists every field and every 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.

Get started

Framework guides

Keyspaces

Keys

Rate limiting

Identities

Authorization

Analytics

Audit logs

Developer portal

Security

Cookbook

Issue and verify your first key

Create a keyspace

Create a key

Verify the key

How you read the verification response

Next steps

Creating keys

Verifying keys

Credits and refill

Keyspaces, keys, identities, and root keys

Create a keyspace

Create a key

Verify the key

​How you read the verification response

​Next steps

Creating keys

Verifying keys

Credits and refill

Keyspaces, keys, identities, and root keys

How you read the verification response

Next steps