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.

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.

Create a root key

Root keys authenticate your requests to the Unkey API (for creating and managing keys).

Go to 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.

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 });

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

console.log(data.key); // This is the key to give to your user

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.

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 "Content-Type: application/json" \
  -d '{
    "key": "THE_KEY_FROM_STEP_3"
  }'

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

const { meta, data } = await 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);

from unkey import Unkey

unkey = Unkey()

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"

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

    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
`credits`	`number?`	Remaining uses (if usage limits set)
`enabled`	`boolean`	Whether the key is enabled
`roles`	`string[]?`	Roles 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., credits 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

Hono

Edge-ready API key verification

Go

Integrate with Go servers

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

Get Started

Core Features

Integration Guides

Advanced Topics

Security

Platform

What’s in the verification response?

Next steps

Next.js

Express

Hono

Go

Add rate limiting

Set usage limits

Add permissions

SDK Reference

​What’s in the verification response?

​Next steps

Next.js

Express

Hono

Go

Add rate limiting

Set usage limits

Add permissions

SDK Reference

What’s in the verification response?

Next steps