Skip to main content
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 a keyspace

A keyspace 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"
  }'

import { Unkey } from "@unkey/api";

const unkey = new Unkey({ rootKey: process.env.UNKEY_ROOT_KEY });

try {
  const { meta, data } = await unkey.keys.createKey({
    apiId: "api_xxxx",
    name: "My First Key",
  });

  console.log(data.key); // This is the key to give to your user
} catch (err) {
  console.error(err);
}

from unkey import Unkey

unkey = Unkey(root_key="your_root_key")

result = unkey.keys.create_key(
    api_id="api_xxxx",
    name="My First Key"
)

print(result.key)  # This is the key to give to your user

package main

import (
    "context"
    "fmt"
    "os"

    unkey "github.com/unkeyed/sdks/api/go/v2"
    "github.com/unkeyed/sdks/api/go/v2/models/components"
)

func main() {
    ctx := context.Background()

    client := unkey.New(
        unkey.WithSecurity(os.Getenv("UNKEY_ROOT_KEY")),
    )

    res, err := client.Keys.CreateKey(ctx, components.V2KeysCreateKeyRequestBody{
        APIID: "api_xxxx",
        Name:  stringPtr("My First Key"),
    })

    if err != nil {
        panic(err)
    }

    fmt.Println(res.V2KeysCreateKeyResponseBody.Key) // Give this to your user
}

func stringPtr(s string) *string { return &s }
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"
  }'

import { Unkey } from "@unkey/api";

const unkey = new Unkey({ rootKey: process.env.UNKEY_ROOT_KEY! });

try {
  const { data } = await unkey.keys.verifyKey({
    key: "THE_KEY_FROM_STEP_3",
  });

  if (!data.valid) {
    // Key is invalid, expired, rate limited, etc.
    console.log("Denied:", data.code);
  }

  // Key is valid, continue with your API logic
  console.log("Key ID:", data.keyId);
} catch (err) {
  console.error(err);
}

from unkey import Unkey

unkey = Unkey(root_key="your_root_key")

result = unkey.keys.verify_key(key="THE_KEY_FROM_STEP_3")

if not result.valid:
    print("Denied:", result.code)
else:
    print("Key ID:", result.key_id)

package main

import (
    "context"
    "fmt"
    "os"

    unkey "github.com/unkeyed/sdks/api/go/v2"
    "github.com/unkeyed/sdks/api/go/v2/models/components"
)

func main() {
    ctx := context.Background()

    client := unkey.New(
        unkey.WithSecurity(os.Getenv("UNKEY_ROOT_KEY")),
    )

    res, err := client.Keys.VerifyKey(ctx, components.V2KeysVerifyKeyRequestBody{
        Key: "THE_KEY_FROM_STEP_3",
    })

    if err != nil {
        panic(err)
    }

    result := res.V2KeysVerifyKeyResponseBody.Data

    if !result.Valid {
        code := "unknown"
        if result.Code != "" {
            code = string(result.Code)
        }
        fmt.Println("Denied:", code)
        return
    }

    fmt.Println("Key ID:", result.KeyId)
}
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 June 2, 2026