Quickstart

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).

Go to Workspace Settings → Root Keys
Click Create New Root Key
Give it a name and select the permissions you need
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:

Field	Type	Description
`valid`	`boolean`	Whether the key passed all checks
`code`	`string`	Status code (`VALID`, `NOT_FOUND`, `RATE_LIMITED`, etc.)
`keyId`	`string`	The key’s unique identifier
`name`	`string?`	Human-readable name of the key
`meta`	`object?`	Custom metadata associated with the key
`expires`	`number?`	Unix timestamp (in milliseconds) when the key will expire. (if set)
`credits`	`number?`	Remaining uses (if usage limits set)
`enabled`	`boolean`	Whether the key is enabled
`roles`	`string[]?`	Permissions attached to the key
`permissions`	`string[]?`	Permissions attached to the key
`identity`	`object?`	Identity info if `externalId` was set when creating the key
`ratelimits`	`object[]?`	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

Getting Started

Platform

Build & Deploy

Networking

Observability

CLI

Security

Keyspaces

AI Code Gen

Audit Logs

CLI

Errors

1. Create a keyspace

2. Create a root key

3. Create an API key

4. Verify the key

What’s in the verification response?

Next steps

Next.js

Express

Bun

Hono

Add rate limiting

Set usage limits

Add permissions

SDK Reference

​1. Create a keyspace

​2. Create a root key

​3. Create an API key

​4. Verify the key

​What’s in the verification response?

​Next steps

Next.js

Express

Bun

Hono

Add rate limiting

Set usage limits

Add permissions

SDK Reference

1. Create a keyspace

2. Create a root key

3. Create an API key

4. Verify the key

What’s in the verification response?

Next steps