Skip to main content

Documentation Index

Fetch the complete documentation index at: https://unkey.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

This guide gets you from zero to a working API key verification as fast as possible. We’ll create a key, then verify it using your preferred method.
Need an account? Sign up free, takes 30 seconds.

​
1. Create an API

An API in Unkey is a container for your keys. Head to your dashboard and create one, or use one you already have. Copy your API ID, it looks like api_xxxx.

​
2. Create a root key

Root keys authenticate your requests to the Unkey API (for creating and managing keys).
  1. Go to Workspace Settings → Root Keys
  2. Click Create New Root Key
  3. Give it a name and select the permissions you need
  4. Copy the key, you won’t see it again
Keep your root key secret. Never expose it in client-side code or commit it to git.

​
3. Create an API key

Now let’s create a key that your users would use to authenticate: 
curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer YOUR_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "api_xxxx",
    "name": "My First Key"
  }'
Save the returned key value, that’s what you’ll verify in the next step.

​
4. Verify the key

This is what you’ll do on every API request to check if a key is valid: 
curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Authorization: Bearer YOUR_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "THE_KEY_FROM_STEP_3"
  }'
A successful response looks like: 
{
  "meta": { "requestId": "req_..." },
  "data": {
    "valid": true,
    "code": "VALID",
    "keyId": "key_xxxx"
  }
}
That’s it! You’ve just verified an API key with Unkey. 🎉

​
What’s in the verification response?

The data object contains everything you need to make authorization decisions:
FieldTypeDescription
validbooleanWhether the key passed all checks
codestringStatus code (VALID, NOT_FOUND, RATE_LIMITED, etc.)
keyIdstringThe key’s unique identifier
namestring?Human-readable name of the key
metaobject?Custom metadata associated with the key
expiresnumber?Unix timestamp (in milliseconds) when the key will expire. (if set)
creditsnumber?Remaining uses (if usage limits set)
enabledbooleanWhether the key is enabled
rolesstring[]?Permissions attached to the key
permissionsstring[]?Permissions attached to the key
identityobject?Identity info if externalId was set when creating the key
ratelimitsobject[]?Rate limit states (if rate limiting configured)
Fields marked with ? are optional and only included when relevant (e.g., remaining only appears if you set a usage limit).

​
Next steps

Now integrate Unkey into your actual application:

Next.js

Protect API routes with middleware

Express

Add key verification to Express routes

Bun

Fast verification with Bun’s native server

Hono

Globally distributed API key verification
Or explore more features:

Add rate limiting

Protect endpoints from abuse

Set usage limits

Cap requests per key for billing tiers

Add permissions

Fine-grained access control

SDK Reference

Full TypeScript SDK docs
Last modified on May 6, 2026