unkey Documentation

Packages Copy Chapter

The TypeScript, Go, and Python clients match the API reference, so method names and fields line up across languages. The Python client ({versions.pySdk}) covers API Management only. The TypeScript and Go clients also cover Compute.

Which package to use Copy Chapter

• @unkey/api, the Go SDK, or the Python SDK when you call several endpoints or want full types.
• @unkey/hono or @unkey/nextjs when you only need to check incoming requests for a valid key. They call keys.verifyKey and give your handler the result.
• @unkey/ratelimit to rate limit user IDs or IP addresses without issuing keys. It adds a timeout and fallback so a network problem can't block your function.
• @unkey/cache for typed caching in your own services. It doesn't call the Unkey API.

One client, both products Copy Chapter

The TypeScript and Go clients cover Compute too, so the same Unkey instance that verifies a key can create a deployment for a Compute app. The Go SDK page shows the same pair in Go. From Python, call Compute endpoints over HTTP. The endpoints are keys.verifyKey and deployments.createDeploymentV3.

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

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

const result = await unkey.keys.verifyKey({ key: "prod_abc123" });

if (!result.data.valid) {
  // result.data.code says why: NOT_FOUND, DISABLED, EXPIRED, RATE_LIMITED, ...
}

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

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

const result = await unkey.deployments.createDeploymentV3({
  project: "my-project",
  app: "api",
  environment: "production",
  oci: { image: "ghcr.io/acme/api:v1.0.0" },
});

console.log(result.data.deploymentId);

For Compute concepts such as projects, apps, and environments, see Projects, apps, and environments.

Response shape Copy Chapter

Every successful response has meta.requestId (quote it when you contact support) and data, the result. Errors are thrown or returned as typed errors per HTTP status. Each SDK page shows how to catch them. See API overview for the raw format.

Next steps Copy Chapter

Api Management Security Overview (`docs/api-management/security/overview.mdx`) Copy Section

title: API key security
sidebarTitle: "Overview"
sources:

• pkg/hash/sha256.go
• internal/services/keys/create.go
• svc/api/routes/v2_keys_verify_key/handler.go
• svc/api/routes/v2_keys_create_key/handler.go
• web/internal/db/src/schema/keyAuth.ts
• web/internal/db/src/schema/util/delete_protection.ts
• web/apps/dashboard/app/api/v1/github/verify/route.ts
• pkg/rbac/permissions.go

Here's how the API keys you issue are protected, and what you can do to keep them safe. For workspace security, such as how your team signs in, see Security.

Keys are stored as hashes Copy Chapter

When you create a key, you get it back once and we keep only a hash. A copy of our database wouldn't give anyone a working key, and we can't show a key again. So show the key when it's created and let users roll it over. Don't promise to show it later. See Key storage.

Recovery is opt-in and separately permissioned Copy Chapter

If your product must show a key more than once, we can turn on encrypted storage for a keyspace. Keys created with recoverable: true are then also stored encrypted with keys unique to your workspace. It's off by default. Creating a recoverable key needs the encrypt_key permission, and reading one back needs decrypt_key, so you can grant recovery narrowly. See Recovering keys for the trade-offs and Recoverable keys for the steps.

Verification doesn't leak Copy Chapter

keys.verifyKey returns NOT_FOUND for several failures, including a root key without permission for the keyspace, so nobody can use it to find out which keys exist. Every verification is recorded in analytics, and verifications made with a root key are also in the audit log.

IP allow lists Copy Chapter

A keyspace can have a list of IP addresses its keys can be verified from. Verification from anywhere else fails with FORBIDDEN. Use it for keys that should only be used from your own servers. See Keyspace settings.

Delete protection Copy Chapter

With delete protection on, you can't delete a keyspace until you turn protection off, so one wrong call can't wipe out a production keyspace and all its keys. See Delete protection.

Root keys are scoped Copy Chapter

A root key has only the permissions you give it, down to one keyspace. For example, api.<api_id>.verify_key lets a service verify keys in one keyspace and nothing else. Give each service its own root key with as few permissions as it needs, so a leaked key does little damage and is easy to replace. See Root key permissions.

Leaked credentials Copy Chapter

GitHub's secret scanning recognizes root keys by their unkey_ prefix. If one is pushed to a public repository, every member of your workspace gets an email. The keys you issue to your users use your own prefixes, and GitHub doesn't scan for them, so delete or reroll a user's key yourself when you learn it leaked. Details are on GitHub secret scanning.

Everything is audited Copy Chapter

Every change to keyspaces, keys, identities, roles, permissions, and portals is in the audit log, with who did it and from where. You can stream it to your own systems. See Audit logs.

Compute Build Overview (`docs/compute/build/overview.mdx`) Copy Section

title: Builds
sidebarTitle: "Overview"
sources:

• svc/ctrl/worker/deploy/deploy_handler.go
• svc/ctrl/worker/deploy/build.go
• svc/ctrl/worker/deploy/railpack.go
• svc/api/openapi/spec/common/EnvironmentBuild.yaml
• svc/api/openapi/spec/common/DeploymentErrorCode.yaml
• svc/api/openapi/spec/paths/v2/environments/updateSettings/V2EnvironmentsUpdateSettingsRequestBody.yaml
• web/internal/db/src/schema/app_build_settings.ts
• web/apps/dashboard/lib/limits.ts
• svc/ctrl/worker/deploy/build_handler.go
• svc/ctrl/worker/cron/buildlimitsync/handler.go

A build turns the source of a git-connected app into the container image your deployment runs. Builds happen on our infrastructure, so you don't need Docker installed to deploy.

Only git-connected apps build. If you deploy a prebuilt image, there is nothing to build: the deployment records the image you named and runs it, and none of the settings on this page apply.

Choose how your app is built Copy Chapter

There is one decision, and it is the Dockerfile path in your environment's build settings.

Leave it empty, the default the dashboard calls Automatic (no Dockerfile), and we detect your language and toolchain from the root directory and build it for you. Set a path and we run a normal Docker build with that file, using the root directory as the build context. See Dockerfile builds.

To get an automatic build right:

• Pin your tool versions in the files your ecosystem already uses. Detection reads them to decide which toolchain to install, so a project that pins nothing can move versions underneath you between builds.
• In a monorepo, set the root directory to the app's own directory, so detection looks at the right project rather than the repository root.
• Set a build command when the detected one is wrong. It can be up to 1000 characters, and it is ignored when a Dockerfile is set.

If detection can't work out how to build your app, the deployment fails with "Unkey could not build this app automatically. For a monorepo, set the root directory to your app and a custom build command in settings, or review the build logs for details." The fix is one of the three above.

Why your build is waiting Copy Chapter

A workspace runs one build at a time on every plan today, so a second deployment sits in pending until the first finishes. Deployments from a prebuilt image queue too, even though they don't build.

Production deployments jump ahead of preview deployments in the queue, so a hot-fix doesn't wait behind a backlog of pull request builds.

A deployment that has waited an hour for its turn fails rather than waiting longer, so a jammed queue surfaces instead of hanging. Deploy again once the queue has drained.

Why your build failed Copy Chapter

A failed build ends the deployment as failed with the error code build_failed. Read the build output on the deployment's detail page in the dashboard, where it streams live and stays afterwards. Common causes are rewritten in plain language above the log, for example a Dockerfile that couldn't be read or a file the build referenced that doesn't exist, and the full log is always underneath.

Problems in your own source, such as a Dockerfile syntax error or a build command that exits non-zero, fail immediately. Retrying them without changing anything gives the same result.

Infrastructure blips are retried for you, up to five attempts and no longer than 30 minutes in total, whichever comes first. A build that takes unusually long and then fails has normally spent that time in retries.

Make builds faster, or skip them Copy Chapter

Build layers are cached per project, up to 25 GB, with layers older than 7 days evicted. Repeat builds of a project whose dependencies haven't changed reuse that cache. A project you haven't deployed in over a week builds from scratch again.

Because every deployment produces its own image, promoting and rolling back never rebuild. They run an image that already exists, which is why a rollback is fast.

Two settings stop a push from building at all:

• Watch paths builds only when a changed file matches one of the environment's glob patterns, so a documentation-only commit doesn't start a build.
• Auto-deploy, turned off, stops pushes from deploying entirely, leaving you to deploy from the dashboard or the API when you choose.

A push that isn't built still appears as a skipped deployment with the reason, so you can tell the difference between a push we ignored and one we never saw. Both settings live on Build settings, and the order they're evaluated in is on GitHub integration.

Your environment variables are available while the build runs without being baked into the image. See Build-time secrets.

Next steps Copy Chapter

Compute Gateway Overview (`docs/compute/gateway/overview.mdx`) Copy Section

title: Gateway
sidebarTitle: "Overview"
sources:

• svc/frontline/routes/proxy/handler.go
• svc/frontline/internal/router/lookup.go
• svc/frontline/internal/db/queries/ingress_route_find_by_fqdn.sql
• svc/ctrl/worker/deploy/create.go
• svc/frontline/internal/policies/engine.go
• svc/frontline/internal/proxy/director.go
• svc/frontline/internal/proxy/forward.go
• svc/frontline/internal/proxy/headers.go
• svc/frontline/middleware/sanitize_headers.go
• svc/frontline/middleware/clickhouse_logging.go
• pkg/timing/entry.go
• svc/api/openapi/spec/common/Policy.yaml

import { ProductLink } from "/snippets/product-link.jsx";

Every deployment on Unkey Compute sits behind the gateway, and there's no other way to reach it. So the gateway can check API keys, rate limit callers, block requests, validate them against your OpenAPI spec, and log them before they reach your app. You set this up with policies. With no policies, the gateway just passes requests through.

What policies can do Copy Chapter

A policy has a name, an on/off switch, up to ten match expressions that pick which requests it applies to, and one rule. There are five kinds of rule:

See Gateway policies to add them from the dashboard, API, or CLI.

What happens to a request Copy Chapter

1. The request arrives at one of your domains, and the gateway finds the deployment it belongs to.
2. The deployment's policies run in list order. Turned-off policies, and policies whose match expressions don't fit the request, are skipped.
3. If a policy rejects the request, the caller gets a 4xx with an err:frontline:... code. The request never reaches your app and doesn't appear in your request log. See Gateway errors for every code.
4. If every policy passes, the gateway forwards the request to your app with the headers below.

What your app receives Copy Chapter

The gateway keeps the original Host header and adds these:

Callers can't fake these. We remove any X-Unkey-* header a client sends before policies run. To get the deployment ID, read the UNKEY_DEPLOYMENT_ID environment variable.

The response to the caller includes X-Unkey-Request-Id, X-Unkey-Region, and X-Unkey-Frontline-Id. Rate limit headers are added when a rate limit applied.

Use keys from API Management Copy Chapter

The API keys the gateway checks live in API Management. To require a key, create a keyspace and keys in API Management, then add the keyspace to an API key authentication policy. The same keys also work if your own code calls keys.verifyKey.

Create the keyspace and keys an authentication policy verifies against, and manage their permissions, rate limits, and credits.

Next steps Copy Chapter

Compute Observe Overview (`docs/compute/observe/overview.mdx`) Copy Section

title: Observability
sidebarTitle: "Overview"
sources:

• web/apps/dashboard/lib/navigation/leaves.ts
• svc/frontline/middleware/clickhouse_logging.go
• svc/frontline/routes/proxy/handler.go
• pkg/clickhouse/schema/022_frontline_requests_raw_v1.sql
• pkg/clickhouse/schema/036_frontline_requests_per_minute_v1.sql
• pkg/clickhouse/schema/037_frontline_requests_per_5m_v1.sql
• pkg/clickhouse/schema/038_frontline_requests_per_15m_v1.sql
• pkg/clickhouse/schema/039_frontline_requests_per_hour_v1.sql
• pkg/clickhouse/schema/040_frontline_requests_per_day_v1.sql
• pkg/clickhouse/schema/023_runtime_logs_raw_v1.sql
• pkg/clickhouse/schema/020_build_steps_v1.sql
• pkg/clickhouse/schema/021_build_step_logs_v1.sql
• pkg/clickhouse/schema/025_instance_checkpoints_v1.sql
• pkg/clickhouse/schema/027_instance_resources_per_minute_v1.sql
• pkg/clickhouse/schema/028_instance_resources_per_hour_v1.sql
• pkg/clickhouse/schema/033_instance_resources_per_15s_v1.sql
• pkg/clickhouse/schema/034_instance_resources_per_day_v1.sql
• pkg/clickhouse/schema/035_instance_resources_per_month_v1.sql
• pkg/clickhouse/schema/029_instance_events_raw_v1.sql
• pkg/clickhouse/user.go
• internal/services/analytics/executor.go
• web/apps/dashboard/lib/limits.ts

We record four kinds of data about your app, with nothing to install in your code:

• Every request the gateway passes to your app.
• Everything your instances print to stdout and stderr.
• CPU, memory, disk, and network for each instance.
• Each build step and its output.

Where to look in the dashboard Copy Chapter

• Request and runtime logs: open a project and click Requests or Logs in the sidebar. Filter by app, environment, deployment, or region.
• Metrics and build steps: open the app, click Deployments, and open a deployment. Its overview has the traffic and resource charts and the build steps. Its Network view shows regions and instances with live request rates.

Rejected requests aren't in the request log Copy Chapter

The request log only has requests that reached your app. Requests rejected by a policy, or that the gateway couldn't route (an unknown hostname, or no running instance), aren't there. So your request log can show less traffic than your callers sent. See Request logs.

Retention Copy Chapter

Each kind of data is kept for a fixed time, shown below. The dashboard can show all of it.

The analytics API has a second limit: your plan's log query range, 3 days on Starter, 7 on Pro, and 14 on Business. You can read back whichever is shorter. A query that reaches further fails with err:user:bad_request:query_range_exceeds_retention instead of returning partial results.

For example, on Starter the analytics API reaches back 3 days into runtime logs that are kept for 90. On Business it reaches 7 days of request logs, not 14, because that's how long they're kept. See Compute limits.

Query the data yourself Copy Chapter

You can query request and runtime logs with SQL through the analytics API, using the gateway_requests_v1 and runtime_logs_v1 tables, to build your own dashboards or alerts. See Query gateway requests and runtime logs. Read build logs through the API with deployments.listBuildLogs. See Build logs. Resource metrics are only in the dashboard.

Platform Ai Coding Overview (`docs/platform/ai-coding/overview.mdx`) Copy Section

title: AI coding
sidebarTitle: "Overview"
sources:

• docs/docs.json
• https://mcp.unkey.com/mcp/v2/install
• https://mcp.unkey.com/mcp/compute/install

You can connect an AI coding assistant like Claude Code, Cursor, or VS Code to Unkey in two ways. It can act on your workspace through Unkey's MCP servers, and it can read these docs while it writes code for you.

Let your assistant act on Unkey Copy Chapter

Unkey hosts two MCP servers. Add one to your assistant with a root key, and it can call the Unkey API for you.

• Unkey: every v2 API endpoint, so keys, keyspaces, identities, permissions, rate limits, analytics, portals, and Compute.
• Compute: only the Compute endpoints, for projects, apps, environments, deployments, domains, and gateway policies.

See Unkey MCP servers for the URLs, the root key to use, and example prompts.

Give your assistant the docs Copy Chapter

• Docs MCP server: lets your assistant search these docs while it works. Its URL is below. You can also add it from the menu next to Copy page at the top of any page, which has Connect to Cursor, Connect to VS Code, Copy MCP Server, and Copy MCP install command.
• Markdown: Copy page copies the page as Markdown you can paste into a chat. Add .md to the end of any docs URL to get the same thing as plain text.
• llms.txt: an index of every page, built for language models. llms-full.txt has the full text of the docs in one file.

https://www.unkey.com/docs/mcp
https://www.unkey.com/docs/llms.txt
https://www.unkey.com/docs/llms-full.txt

Use the CLI Copy Chapter

Assistants that run terminal commands can also use the unkey CLI. Pass --output=json so they get the full API response. See Install the CLI.

Next steps Copy Chapter

Platform Api Overview (`docs/platform/api/overview.mdx`) Copy Section

title: HTTP API basics
sidebarTitle: "Overview"
sources:

• svc/api/openapi/openapi-generated.yaml
• svc/api/openapi/spec/common/Meta.yaml
• svc/api/openapi/spec/common/Pagination.yaml
• svc/api/openapi/spec/paths/v2/apis/listKeys/V2ApisListKeysRequestBody.yaml
• svc/api/openapi/spec/paths/v2/apis/listKeys/V2ApisListKeysResponseBody.yaml
• svc/api/internal/pagination/pagination.go
• svc/api/routes/v2_ratelimit_list_overrides/handler.go
• pkg/zen/auth.go

Compute and API Management share one HTTP API. Here's how to make a request, read the response, and page through lists.

Make a request Copy Chapter

Send a POST with a JSON body to https://api.unkey.com/v2/{service}.{procedure}. There are no path or query parameters. The only GET routes are /v2/liveness, the health check, and /openapi.yaml and /reference, which serve the OpenAPI document and a browsable reference. See RPC naming convention for how endpoints are named.

curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Authorization: Bearer <root key>" \
  -H "Content-Type: application/json" \
  -d '{"key": "sk_live_..."}'

Put a root key in the Authorization: Bearer header. See API authentication.

Read the response Copy Chapter

Every response is a JSON object with meta. A success adds data, and a failure adds error instead.

{
  "meta": { "requestId": "req_2c9a0jf23l4k567" },
  "data": { "keyId": "key_1234abcd" }
}

Page through lists Copy Chapter

List endpoints use a cursor instead of page numbers. Each request takes an optional limit and cursor, and each response has a pagination object next to data. The example uses apis.listKeys, but every list endpoint works the same way.

Maximum items to return. For apis.listKeys it's 1 to 100, default 100. Most list endpoints default to 100, but ratelimit.listOverrides defaults to 50. Send limit if the page size matters to you.

The pagination.cursor value from the previous response, sent back unchanged. Leave it out for the first page. Cursors can expire, so don't store them long term or build them yourself.

Keep the other request fields the same on every page. If you change a filter partway through, the cursor no longer works.

Platform Cli Overview (`docs/platform/cli/overview.mdx`) Copy Section

title: The unkey CLI
sidebarTitle: "Overview"
sources:

• build/cli/main.go
• cmd/api/root.go
• cmd/api/util/flags.go
• cmd/api/analytics/root.go
• cmd/auth/main.go
• cmd/deploy/main.go
• cmd/healthcheck/main.go
• pkg/cli/parser.go
• .goreleaser.yaml

The unkey CLI lets you do from your terminal what you'd do with the API. It covers both products. Nearly every API endpoint has a matching unkey api <group> <command>. The exception is the customer portal's end-user endpoints, which use a portal session instead of a root key.

There are also three top-level commands: unkey deploy deploys a prebuilt container image to Compute, unkey auth login stores a root key so you don't pass it on every call, and unkey healthcheck checks a URL from a script.

Command shape Copy Chapter

Commands look like unkey <command> [subcommand] [flags] [arguments]. unkey --help, unkey <command> --help, and unkey help <command> print usage, and unkey --version prints the installed version.

Every unkey api command shares five flags for auth, output, and a raw request body. They're on CLI output and shared flags, along with flag syntax, so each command page only lists its own flags.

Command groups Copy Chapter

unkey api has 14 groups, one per API service. Each command has its own page in the CLI section of the product it belongs to.

Compute Copy Section

Apps, deployments, domains, environments, gateway policies, and the GitHub App installation are Compute resources.

API Management Copy Section

Keyspaces, keys, identities, permissions and roles, rate limiting, and the customer portal are API Management resources.

analytics appears in both tables because two of its commands read Compute data and two read API Management data.

Top-level commands Copy Chapter

Next steps Copy Chapter

Platform Root Keys Overview (`docs/platform/root-keys/overview.mdx`) Copy Section

title: Root keys
sidebarTitle: "Overview"
sources:

• svc/api/routes/v2_root_keys_create_key/handler.go
• svc/api/routes/v2_root_keys_update_key/handler.go
• svc/api/routes/v2_root_keys_delete_key/handler.go
• web/apps/dashboard/app/(app)/[workspaceSlug]/root-keys/page.tsx
• web/apps/dashboard/lib/trpc/routers/key/reroll/index.ts
• web/apps/dashboard/lib/trpc/routers/settings/root-keys/delete.ts
• web/apps/dashboard/components/api-keys-table/components/actions/components/rotate-key/rotate-key.constants.ts
• web/internal/keys/src/util.ts
• internal/services/caches/caches.go

import { DashboardScreenshot } from "/snippets/dashboard-screenshot.jsx";

A root key is the credential your services, CI jobs, and agents use to call Unkey through the API or CLI. It belongs to one workspace and has no permissions by default. You assign permissions to let it perform its task, such as deploying an app or verifying customer API keys.

Start with Root key permissions to decide what access the key needs. Then use Configure root keys to create it in the dashboard or API. This page explains how to store, rotate, and delete it.

A root key isn't one of the API keys you issue to your own users. You create and verify those through the API, using a root key. See API Management concepts.

Manage root keys on the workspace's Root Keys page. You need the admin role to manage them in the dashboard. Automation can manage root keys through the API with the required root key permissions.

What a root key looks like Copy Chapter

A root key starts with unkey_, followed by random characters. It's shown to you only once (see Key storage). The bearer key identifies the workspace for API requests. Permission URNs also include that workspace's ID.

A root key has no credit limit or rate limit of its own. You can set an expiry when creating it through the API. Use short-lived keys for temporary jobs and agents.

Create a root key Copy Chapter

Give each service, job, or agent its own root key. Choose the resource scope and actions in Root key permissions, then follow Configure root keys to create it in the dashboard or API.

Store the secret in your secret manager. You can't retrieve it again. The audit log records who created the key and which permissions it received.

Edit a root key Copy Chapter

From the key's row menu, choose Edit root key to change its name or permissions. Saving replaces the complete permission set, so review all policies before saving. See Edit permissions for dashboard and API instructions.

Rotate a root key Copy Chapter

Rotating gives you a new root key with the same name and permissions, and stops the old one after a grace period.

1. Choose Rotate root key from the row menu.
2. Pick a grace period: revoke immediately, 15 minutes, 1 hour, 6 hours, or 24 hours.
3. Check the confirmation, click Rotate root key, then confirm the rotation.
4. Copy the new key. It's shown once, like a new key.
5. Update your services before the grace period ends.

When the grace period ends, requests with the old key fail with err:unkey:authorization:forbidden. If the old key was already set to expire sooner, it stops at that earlier time.

Rotate on a schedule that fits your security policy, and right away if a key has been exposed. With "revoke immediately", the old key stops working as soon as the new one exists.

Delete a root key Copy Chapter

Choose Delete root key from the row menu and confirm. You can't undo this. The key can no longer authenticate after the deletion propagates. The audit log records the deletion. Delete keys for services you've retired instead of leaving them active.

If a root key leaks Copy Chapter

Rotate it with "revoke immediately" or delete it, then remove the secret from wherever it was exposed. The key keeps working until you do.

If a root key is pushed to a public GitHub repository, GitHub secret scanning reports it and every member of the workspace gets an email saying where it was found.

Unkey stores root keys hashed, so it can't recover the secret, only identify which key ID a request used. That's another reason to create one key per service.

Permissions reference Copy Chapter

Platform Security Overview (`docs/platform/security/overview.mdx`) Copy Section

title: Security
sidebarTitle: "Overview"
sources:

• pkg/hash/sha256.go
• pkg/encryption/aes.go
• svc/api/routes/v2_keys_create_key/handler.go
• svc/vault/internal/vault/rpc_encrypt.go
• internal/services/keys/create_v1.go
• web/apps/dashboard/lib/auth/roles.ts
• web/apps/dashboard/lib/trpc/trpc.ts
• web/apps/dashboard/lib/trpc/routers/workspace/changeName.ts
• web/apps/dashboard/lib/trpc/routers/api/updateDeleteProtection.ts
• web/internal/db/src/schema/util/delete_protection.ts
• SECURITY.md

Unkey stores every API key and root key as a SHA-256 hash, so you can issue and verify keys without keeping a homegrown key table. A copy of the database isn't a list of working keys. This page covers that storage and what you can turn on around it.

How Unkey stores API keys Copy Chapter

Unkey doesn't store the API key. On create, it hashes the full key string with SHA-256 and stores the hash as standard base64, not hex. Verification hashes the key your user sent and compares the two strings. There's no salt. The plaintext is returned once, in the create response, and isn't kept.

See the OWASP Secrets Management Cheat Sheet and the OWASP REST Security Cheat Sheet for hashing and storing secrets you only need to verify. SHA-256 here is a fast hash of a random key, not a password hash such as bcrypt or Argon2.

If a keyspace must show a key again, you opt in to an encrypted copy beside the hash. The copy is AES-256-GCM, the keyring is the workspace, and only a root key with decrypt permission can read the key back. Verification still uses the hash. See Key storage and Recovering keys.

Should you build your own API key system? Copy Chapter

You can. What moves to Unkey is generating the random key, storing only the hash, and checking it on each request. keys.createKey issues the key. keys.verifyKey checks enabled, expiry, credits, rate limits, permissions, and the IP allow list. If you already have hashes and the format matches, Migrating keys covers importing them.

You still run your API, unless you deploy it on Compute. You still decide the HTTP status you return to your users. You stop maintaining the keys table, the hash comparison, and, if you use Unkey for them, the rate-limit counters and the monthly credit balance.

How Unkey protects the workspace Copy Chapter

Two controls apply to the workspace itself, separate from how keys are stored.

Access is scoped. A root key only works in the workspace that issued it, and every endpoint needs a specific permission. Dashboard users are either an admin or a developer. A developer who tries an admin-only action gets This action requires admin privileges. See Team.

Changes are audited. Changes made in the dashboard appear in the audit log with who made them, the event, and a description. For example, renaming a workspace logs workspace.update. How long entries are kept depends on your plan. See Limits.

Security features you can use Copy Chapter

Reporting a vulnerability Copy Chapter

If you find a security issue, email [email protected] with steps to reproduce. Don't open a public issue or pull request. Reports about api.unkey.com and app.unkey.com are in scope. The docs site, the marketing site, and misconfigured self-hosted setups aren't. The full policy is in SECURITY.md.

Platform Workspace Overview (`docs/platform/workspace/overview.mdx`) Copy Section

title: Workspaces
sidebarTitle: "Overview"
sources:

• web/internal/db/src/schema/workspaces.ts
• web/internal/id/src/generate.ts
• web/apps/dashboard/lib/trpc/routers/workspace/create.ts
• web/apps/dashboard/app/new/hooks/use-workspace-step.tsx
• web/apps/dashboard/lib/slugify.ts
• web/apps/dashboard/lib/limits.ts
• web/apps/dashboard/lib/support.ts

A workspace is the top-level container. Everything you create sits in exactly one. Whether you deploy an app with Compute or only issue API keys, it's the same workspace with different parts in use.

Most teams need one workspace. Make a second when you need hard isolation: separate billing for two business units, or a client whose data must never sit next to yours.

What sits in a workspace Copy Chapter

Everything on this site is scoped to a workspace: the team and roles, billing plans and limits, root keys, keyspaces and keys, and Compute projects with their apps and environments. A root key from one workspace can't touch another.

Slug and ID Copy Chapter

A workspace has two identifiers. They do different jobs.

The URL handle you choose when creating the workspace. It appears in every dashboard URL as app.unkey.com/<slug>/..., must be unique across Unkey, and can't be changed later. It's 3 to 64 characters of lowercase letters, digits, and hyphens, and can't start or end with a hyphen. The dashboard derives a slug from the workspace name as you type and lets you edit it before creating.

A generated identifier prefixed with ws_. Use it when an API call or a support request needs to name the workspace. Copy it from Settings > General. See Workspace settings.

Create a workspace Copy Chapter

<Frame>
  
</Frame>

Delete a workspace Copy Chapter

The dashboard and the API don't offer workspace deletion. To close a workspace, email [email protected] from an address that belongs to a workspace admin. Make sure you cancel any paid plans under Settings > Billing so nothing renews while the request is handled.

Scripts Brands README (`docs/scripts/brands/README.md`) Copy Section

Illustration brand marks

These marks identify integrations, not endorsements. Keep their original geometry and proportions. Full-color marks retain their source colors; monochrome marks use a light or dark treatment for contrast.

The artwork generator embeds these local vectors, so card rendering does not depend on third-party requests. Cloudflare uses the standalone cloud symbol paths from its horizontal logo. Source files are retained here to make provenance and future brand updates reviewable.

Platform Workspace Audit Logs Overview (`docs/platform/workspace/audit-logs/overview.mdx`) Copy Section

title: Audit logs
sidebarTitle: "Overview"
sources:

• pkg/auditlog/log.go
• pkg/auditlog/actors.go
• pkg/auditlog/events.go
• internal/services/auditlogs/insert.go
• svc/api/routes/v2_keys_verify_key/handler.go
• web/apps/dashboard/lib/limits.ts
• pkg/clickhouse/schema/025_audit_logs_raw_v1.sql
• web/apps/dashboard/app/(app)/[workspaceSlug]/audit/components/controls/components/logs-filters/index.tsx

The audit log records every change made through the API or the dashboard: who did it, what they did, what it touched, and from where. Use it to answer "who deleted that key?" or to show a compliance reviewer. Entries are written automatically, and nobody can edit or delete them.

What an entry contains Copy Chapter

Each entry has:

• An event, such as key.create or portal.session.exchange. See Audit log event types.
• An actor, with a type, ID, and name. The type is user (someone in the dashboard), rootkey (an API call), portalEndUser (one of your customers in a developer portal), github (a push or pull request on a connected repository), or system (Unkey itself).
• The resources it touched, each with a type, ID, name, and optional details such as the fields that changed.
• The caller's IP address and user agent, and a readable description.
• A correlation ID that groups entries from one action, such as a key creation and the permissions it attached.

Every entry is in the unkey_mutations bucket, the only option in the dashboard's Bucket filter.

Which actions are logged Copy Chapter

Every create, update, and delete is logged, for keyspaces, keys, identities, roles, permissions, rate limit namespaces and overrides, portals, every Compute resource, and workspace and team changes. Reads aren't logged, with two exceptions: key.verify when a root key calls keys.verifyKey, and ratelimit.limit when a root key checks a rate limit. Verifications by the gateway or a portal session aren't in the audit log. They're in analytics.

Reading the log Copy Chapter

Open Audit log in the dashboard sidebar. Entries are newest first. Expand one to see its resources, description, IP address, and user agent. Filter by Events, Users, Root Keys, Bucket, and time range. Press F to open the filters and Q to reopen saved filters. Every workspace role can read the log, including viewers, but only admins see keys in the Root Keys filter.

Retention Copy Chapter

Your plan sets how long entries are kept. Check the Audit log retention row on Settings > Limits. See Limits.

No plan keeps audit logs longer than 90 days. To keep them longer, or in your own systems, stream them out with a log drain.

Web Apps Design Docs Index (`web/apps/design/docs/index.mdx`) Copy Section

title: Overview sidebar: order: 0 Copy Chapter

.Mintlify Assistant (`docs/.mintlify/Assistant.md`) Copy Section

You are the Unkey documentation assistant. Help developers use Unkey accurately, using these docs as your source of truth.

Tone Copy Chapter

• Be friendly and guiding. Lead with the answer, then a short next step when it helps.
• Prefer plain language over jargon. When a Unkey term matters, use the glossary term and say which product it belongs to.
• Keep answers focused. Link to the relevant docs page instead of restating a whole guide.

Product context Copy Chapter

Unkey has two separate products plus shared platform pages. A reader can use either product without the other. Always say which product an answer belongs to when it could be ambiguous.

• Compute: builds, deploys, and runs apps behind a gateway (projects, apps, environments, deployments, gateway policies).
• API Management: issues and verifies API keys, enforces rate limits, manages identities and permissions, and reports usage (keyspaces, keys, identities, credits).
• Platform (shared): workspace, billing, root keys, CLI, audit logs, and error codes.

Accuracy rules Copy Chapter

• Only state product behavior, API shapes, limits, plans, and error codes that these docs support.
• If the docs do not clearly cover something, say so. Do not invent endpoints, fields, permissions, plan limits, or dashboard paths.
• Prefer citing or linking the page that supports your answer. When you are unsure between two meanings, ask a clarifying question or point to the glossary.
• Never invent or guess secret values, root keys, or API keys.

Terminology Copy Chapter

Follow the glossary. These trips people up most:

• Root key vs API key: a root key (unkey_…) authenticates you to the Unkey API and CLI. An API key is a credential you issue to users of your application and verify with keys.verifyKey.
• Workspace: top-level container (ws_ ID). Do not call it a project or organization.
• Keyspace: API Management container for keys (called an API in endpoint names like apis.createApi).
• Project / app: Compute only. A project groups apps; an app is what you deploy.
• Environment: in Compute, production or preview. In API Management, an optional label on a key (live / test) that does not change key behavior.
• Rate limiting: three different features share this name — the standalone ratelimit.limit API, key/identity rate limits checked on verify, and Compute gateway rate-limit policies. Say which one you mean.
• Verify: usually keys.verifyKey in API Management. Compute also has custom-domain verification and gateway key-auth.
• Role: dashboard roles (admin / developer) are not the same as API Management roles on keys.
• Tier vs plan: billing says "tier" for API Management and "plan" for Compute; they bill separately.

API shape Copy Chapter

• Unkey API calls are HTTP POST to https://api.unkey.com/v2/{service}.{procedure} with a root key in the Authorization: Bearer header.
• Root keys are workspace-scoped; you do not pass a workspace ID with the key.
• Error codes look like err:{system}:{category}:{specific} and each has a page at /errors/{system}/{category}/{specific}.

Compute pricing Copy Chapter

Explain Compute billing from these rules. Point people to unkey.com/pricing for current unit rates, plan fees, included credits, and the calculator at the bottom of that page. Do not invent rates that aren't on that page or in these docs.

Each Compute plan has a monthly fee and included usage credit. Usage above the credit is billed on:

• vCPU: average active virtual CPU per running instance. Billed on actual usage, not the configured ceiling. Idle time waiting on I/O is not active CPU.
• Memory: average memory used per running instance. Billed on actual usage, not the configured ceiling.
• Ephemeral disk: volume mounted per instance. Billed on the allocated size while the instance runs, up to 10 GiB per instance.
• Egress: total outbound network data transfer per month.
• Active / verified keys: distinct keys with at least one verification during the month through a Key Auth policy on Compute (Unkey Deploy). These bill to the Compute project, not an API Management keyspace.

Runtime settings are ceilings. Most people never pin 100% CPU or memory. If someone configures 1 vCPU but averages 0.5 vCPU, bill the 0.5. Work an example from the published per-second rates on the pricing page (for example, cost ≈ average_vCPU × seconds_running × vCPU_rate), then suggest the calculator for a full estimate. Preview deployments bill at the same rates as production. Unused included credits do not roll over.

Escalation Copy Chapter

• When someone needs a human (account access, billing changes, enabling a support-gated feature, workspace deletion, or anything the docs say requires support), direct them to [email protected].
• You may mention Discord (https://unkey.com/discord) as a community option, but email support first for account and support-gated requests.
• For outages or degraded service, point to https://status.unkey.com.

Scope Copy Chapter

• Stay on Unkey product and docs questions.
• Do not give legal, security-audit, or competitive advice beyond what these docs state.
• Do not invent comparisons to other vendors.

Platform Glossary (`docs/platform/glossary.mdx`) Copy Section

title: Glossary
sources:

• web/internal/db/src/schema/keys.ts
• web/internal/db/src/schema/limits.ts
• web/internal/db/src/schema/workspaces.ts
• web/internal/db/src/schema/keyAuth.ts
• web/apps/dashboard/lib/auth/roles.ts
• pkg/hash/sha256.go
• web/apps/dashboard/lib/stripe/deployPlan.ts

Look up a term here. Some terms mean different things in different products, so each entry starts with the product that owns it.

Terms with more than one meaning Copy Chapter

App Copy Section

Compute. A service you deploy, inside a project. It has a GitHub repository or an image as its source, two environments, build and runtime settings, and a history of deployments. On this site, "app" always means this. When we mean the software you run anywhere, including outside Unkey, we say "your application".

Environment Copy Section

Compute. Every app has two environments, production and preview, and each deployment belongs to one. Environment variables, runtime settings, and gateway policies are set per environment. API Management uses the same word for an optional label on a key, the key's environment field, so you can tag keys as live or test. The label doesn't change how the key behaves, and it has nothing to do with Compute environments.

Rate limiting Copy Section

Three different features share this name:

• API Management: the standalone ratelimit API. You call ratelimit.limit with your own identifier and namespace and get an allow or deny.
• API Management: key and identity rate limits. They're attached to a key or an identity and checked when the key is verified.
• Compute: the gateway rate limit policy. The gateway applies it to requests before they reach your app.

Verify Copy Section

API Management. Key verification is keys.verifyKey: you send a key, and we tell you whether it's valid and, if not, why. Compute uses the word twice more: custom domain verification, where you prove you control a domain before the gateway serves it, and the gateway key-auth policy, which verifies keys on incoming requests so your app only sees verified callers.

Platform Copy Chapter

Workspace Copy Section

Platform. The top-level container for everything else. It has a slug used in dashboard URLs, a ws_ ID used in the API, and its own team, billing, and limits. Workspaces are fully separate from each other. See Workspaces.

Root key Copy Section

Platform. The credential for calling the Unkey API and using the CLI. A root key belongs to one workspace, has a list of permissions, and is stored as a SHA-256 hash like every other key. See Root keys.

Role Copy Section

Platform. Admin or developer, given to each dashboard user per workspace. Developers can work with every resource in the workspace. Admins can also manage members, rename the workspace, manage root keys, and change billing. These aren't the roles you attach to API keys in API Management, which group permissions for your own users. See Team.

Tier and plan Copy Section

Platform. The billing page says "tier" for API Management (Free by default) and "plan" for Compute (Starter, Pro, or Business). They're billed separately to the same payment method. See Plans.

Limits Copy Section

Platform. Your workspace's ceilings, shown under Settings > Limits: monthly API operations, log and audit log retention, log drains, team members, and Compute resources. Most come from your API tier and Compute plan. See Limits.

Delete protection Copy Section

Platform. A setting on keyspaces, projects, and apps that blocks deletion while it's on. A delete attempt returns err:unkey:application:protected_resource. See Delete protection.

API Management Copy Chapter

Keyspace Copy Section

API Management. A container for API keys, called an API in endpoint names (apis.createApi). Each key belongs to one keyspace. A keyspace sets the default prefix and length for new keys, and has settings for encrypted key storage, an optional IP allow list, and delete protection.

Key Copy Section

API Management. A credential you give to a user of your application and verify on each request. A key has a prefix and can have a name, metadata, an expiry, credits, rate limits, permissions and roles, and an identity. We store only its hash, unless it's a recoverable key.

Identity Copy Section

API Management. One of your users or tenants, identified by your own externalId, that several keys can belong to. Rate limits on an identity are shared by all of its keys.

Credits Copy Section

API Management. The number of uses a key has left. Each verification uses one, and credits can refill on a schedule. At zero, verification reports the key as out of usage.

Permission and role (keys) Copy Section

API Management. Permissions are strings you define and attach to keys, directly or through roles. Verification can check that a key has a permission or matches a permission query. These are separate from dashboard roles.

Recoverable key Copy Section

API Management. A key created with recoverable: true in a keyspace with encrypted storage turned on. We keep an encrypted copy, so you can read the key again later. See Key storage.

Compute Copy Chapter

Project Copy Section

Compute. A group of apps, usually one per codebase or product. Compute usage is billed and reported per project, and a project can have delete protection.

Deployment Copy Section

Compute. One built version of an app, running in one environment. It's created from a git commit, an image, or an existing deployment. You can promote it or roll back to it, and it keeps the gateway policies that were in place when it was created.

Gateway Copy Section

Compute. What sits in front of every deployment and receives its traffic. It handles HTTPS, routes requests by domain, and applies the environment's policies: key authentication, rate limiting, firewall rules, OpenAPI validation, and logging.

Gateway policy Copy Section

Compute. A rule the gateway applies to requests for an environment. The key-auth policy uses a keyspace from API Management, which is where the two products connect.

Replica Copy Section

Compute. One running instance of a deployment in a region. Autoscaling can add replicas up to your plan's replicas-per-region limit. See Limits.

Spend budget Copy Section

Compute. A monthly dollar cap on Compute usage, set by an admin. It emails you at 50, 75, and 100 percent and can optionally stop your workloads at 100 percent. See Spend budget.

Scripts Pending Upstream (`docs/scripts/pending-upstream.txt`) Copy Section

Endpoints present in svc/api/openapi/openapi-generated.yaml but not yet published

to the Speakeasy spec both API reference tabs render. Listing them in docs.json

fails `mint validate`, so they stay out of the reference until upstream publishes

them; docs-lint downgrades their coverage gap to a warning while they are here.

`mise run docs-check` prints the current pending set under "pending upstream publish".

/v2/workspace.getLimits
/v2/workspace.getUsage

Internal to the hosted portal and x-excluded on purpose; never listed.

/v2/portal.exchangeCode
/v2/portal.getVerifications
/v2/portal.listKeys
/v2/portal.rerollKey

GET /v2/liveness is published without x-codeSamples and `mint validate` fails to generate its page.

/v2/liveness

Snippets Cli Install (`docs/snippets/cli-install.mdx`) Copy Section

import { versions } from "/snippets/versions.mdx";

npm install unkey

Without Node, download the archive for your platform from the releases page and put the unkey binary on your PATH instead. Both paths ship the same binary, currently {versions.cli}.

Snippets Root Key Prereq (`docs/snippets/root-key-prereq.mdx`) Copy Section

Snippets Versions (`docs/snippets/versions.mdx`) Copy Section

export const versions = {
cli: "2.0.150",
tsApi: "2.5.1",
tsRatelimit: "2.1.4",
tsHono: "2.0.0",
tsNextjs: "2.0.0",
tsCache: "1.5.0",
tsNuxt: "1.1.15",
goSdk: "v3.0.1",
pySdk: "3.0.3",
};

Api Management Analytics Examples (`docs/api-management/analytics/examples.mdx`) Copy Section

title: Analytics query examples
sidebarTitle: "Query examples"
sources:

• pkg/clickhouse/query-parser/validation.go
• pkg/clickhouse/schema/001_key_verifications_raw_v2.sql
• pkg/clickhouse/schema/003_key_verifications_per_hour_v3.sql
• pkg/clickhouse/schema/004_key_verifications_per_day_v3.sql
• pkg/clickhouse/schema/006_ratelimits_raw_v2.sql
• pkg/clickhouse/schema/008_ratelimits_per_hour_v2.sql

Copy these queries to answer common questions. Send each as the query string of analytics.getVerifications or analytics.getRatelimits. You don't need a workspace filter.

Some of these reach back seven days or a calendar month, which is longer than some plans keep data. Check your retention first. If a query fails with err:user:bad_request:query_range_exceeds_retention, shorten the window.

Verifications Copy Chapter

Total verifications in the last 24 hours Copy Section

The per-hour rollup already sums verifications, so read sum(count) rather than count().

SELECT sum(count) AS verifications
FROM key_verifications_per_hour_v1
WHERE time >= now() - INTERVAL 24 HOUR

Outcomes per hour for the last day Copy Section

SELECT
  time,
  outcome,
  sum(count) AS verifications
FROM key_verifications_per_hour_v1
WHERE time >= now() - INTERVAL 24 HOUR
GROUP BY time, outcome
ORDER BY time, outcome

Valid versus rejected, per day Copy Section

sumIf lets you split one scan into several totals. Per-day time is a Date, so compare with today().

SELECT
  time AS day,
  sumIf(count, outcome = 'VALID') AS valid,
  sumIf(count, outcome != 'VALID') AS rejected,
  round(100 * valid / (valid + rejected), 2) AS valid_percent
FROM key_verifications_per_day_v1
WHERE time >= today() - INTERVAL 7 DAY
GROUP BY day
ORDER BY day

Usage per customer this month Copy Section

external_id is your ID for the identity behind each key, so it's a good way to bill.

SELECT
  external_id,
  sum(count) AS verifications,
  sum(spent_credits) AS credits
FROM key_verifications_per_day_v1
WHERE time >= toStartOfMonth(today())
  AND external_id != ''
GROUP BY external_id
ORDER BY verifications DESC
LIMIT 100

Keys hitting rate limits or running out of credits Copy Section

SELECT
  key_id,
  external_id,
  sumIf(count, outcome = 'RATE_LIMITED') AS rate_limited,
  sumIf(count, outcome = 'USAGE_EXCEEDED') AS usage_exceeded
FROM key_verifications_per_hour_v1
WHERE time >= now() - INTERVAL 1 DAY
GROUP BY key_id, external_id
HAVING rate_limited > 0 OR usage_exceeded > 0
ORDER BY rate_limited + usage_exceeded DESC
LIMIT 50

Latency percentiles from the raw table Copy Section

Latency stats have to come from the raw table. Raw time is in milliseconds, so convert the bound.

SELECT
  round(avg(latency), 2) AS avg_ms,
  round(quantile(0.5)(latency), 2) AS p50_ms,
  round(quantile(0.99)(latency), 2) AS p99_ms
FROM key_verifications_v1
WHERE time >= toUnixTimestamp64Milli(now() - INTERVAL 1 HOUR)

Verifications per tag Copy Section

Tags are an array on each row. arrayJoin gives one row per tag, and has keeps rows with a specific tag.

SELECT
  arrayJoin(tags) AS tag,
  sum(count) AS verifications
FROM key_verifications_per_day_v1
WHERE time >= today() - INTERVAL 7 DAY
GROUP BY tag
ORDER BY verifications DESC

SELECT sum(count) AS checkout_calls
FROM key_verifications_per_day_v1
WHERE time >= today() - INTERVAL 7 DAY
  AND has(tags, 'endpoint:checkout')

Hourly buckets from the raw table Copy Section

When you need a dimension the rollups don't carry, such as region, bucket the raw rows yourself.

SELECT
  toStartOfHour(fromUnixTimestamp64Milli(time)) AS hour,
  region,
  count() AS verifications
FROM key_verifications_v1
WHERE time >= toUnixTimestamp64Milli(now() - INTERVAL 6 HOUR)
GROUP BY hour, region
ORDER BY hour, region

Gateway-verified versus API-verified Copy Section

Keys verified by a Compute gateway key-auth policy carry source = 'gateway' and the app_id of the app that fronted them. Direct keys.verifyKey calls carry source = 'api' and an empty app_id.

SELECT
  source,
  app_id,
  sum(count) AS verifications
FROM key_verifications_per_day_v1
WHERE time >= today() - INTERVAL 7 DAY
GROUP BY source, app_id
ORDER BY verifications DESC

Rate limits Copy Chapter

Pass rate per namespace over the last day Copy Section

SELECT
  namespace_id,
  sum(passed) AS passed,
  sum(total) AS total,
  round(100 * passed / total, 2) AS pass_percent
FROM ratelimits_per_hour_v1
WHERE time >= now() - INTERVAL 24 HOUR
GROUP BY namespace_id
ORDER BY total DESC

Most rejected identifiers Copy Section

SELECT
  identifier,
  sum(total) - sum(passed) AS rejected
FROM ratelimits_per_hour_v1
WHERE time >= now() - INTERVAL 24 HOUR
GROUP BY identifier
HAVING rejected > 0
ORDER BY rejected DESC
LIMIT 25

Checks that used an override Copy Section

SELECT
  override_id,
  identifier,
  countIf(passed) AS passed,
  countIf(NOT passed) AS rejected
FROM ratelimits_v1
WHERE time >= toUnixTimestamp64Milli(now() - INTERVAL 6 HOUR)
  AND override_id != ''
GROUP BY override_id, identifier
ORDER BY rejected DESC

Combining tables Copy Chapter

Use a CTE to answer a two-step question.

WITH top_customers AS (
  SELECT external_id
  FROM key_verifications_per_day_v1
  WHERE time >= today() - INTERVAL 7 DAY
    AND external_id != ''
  GROUP BY external_id
  ORDER BY sum(count) DESC
  LIMIT 10
)
SELECT
  time,
  external_id,
  sum(count) AS verifications
FROM key_verifications_per_hour_v1
WHERE time >= now() - INTERVAL 24 HOUR
  AND external_id IN (SELECT external_id FROM top_customers)
GROUP BY time, external_id
ORDER BY time, external_id

If a query is rejected, the troubleshooting page maps each error to its fix.

Api Management Analytics Query Language (`docs/api-management/analytics/query-language.mdx`) Copy Section

title: Analytics query language
sidebarTitle: "Query language"
sources:

• pkg/clickhouse/query-parser/parser.go
• pkg/clickhouse/query-parser/validation.go
• pkg/clickhouse/query-parser/tables.go
• pkg/clickhouse/query-parser/filter.go
• pkg/clickhouse/query-parser/limits.go
• pkg/clickhouse/query-parser/time_range.go
• pkg/clickhouse/schema/001_key_verifications_raw_v2.sql
• pkg/clickhouse/schema/002_key_verifications_per_minute_v3.sql

Analytics queries are ClickHouse SQL. You can filter, group, aggregate, and join your own data. Anything not listed here is rejected with a 400 that names the problem.

What a query must be Copy Chapter

A query is one SELECT statement with a FROM clause. An empty body or a second statement fails with err:user:bad_request:invalid_analytics_query. Anything that isn't a SELECT (INSERT, SHOW, DESCRIBE, and so on) fails with err:user:bad_request:invalid_analytics_query_type.

You can use WHERE, GROUP BY, HAVING, ORDER BY, LIMIT and OFFSET, WITH (CTEs), subqueries in FROM and IN (...), JOIN, UNION, and EXCEPT. The same rules apply to every nested SELECT.

These aren't allowed:

• A SETTINGS clause.
• Table functions such as numbers(), url(), or remote().
• IN followed by a table name. Write IN (SELECT ... FROM ...) instead.

Tables Copy Chapter

Only the tables listed on the overview, and CTEs you define, can appear in FROM and JOIN. Any other table fails with err:user:bad_request:invalid_analytics_table. Aliases (FROM key_verifications_v1 AS v) work as usual.

Filters and limits added for you Copy Chapter

You don't need a workspace filter. Every query only sees your workspace's rows, and only the keyspaces or namespaces your root key can read. Your own WHERE narrows it further. A query for a keyspace you can't see returns no rows, not an error.

Every SELECT is capped at your workspace's result row limit, 10,000,000 by default. A smaller LIMIT you write is kept.

Functions Copy Chapter

Only the functions in this table are allowed. Names can be any case. Any other function fails with err:user:bad_request:invalid_analytics_function. Commonly missed ones include toUnixTimestamp, avgMerge, quantilesTDigestMerge, multiIf, argMax, topK, median, dateDiff, row_number, rank, lagInFrame, and every JSONExtract* except JSONExtractString. An allowed aggregate still works with OVER, as in sum(spent_credits) OVER (PARTITION BY key_id). Operators such as +, =, <, AND, OR, NOT, LIKE, IN, and BETWEEN always work.

If you need a function that isn't listed, tell us which one.

Working with time Copy Chapter

In the raw tables, time is milliseconds since the Unix epoch (Int64), so convert when you compare with "now": time > toUnixTimestamp64Milli(now() - INTERVAL 1 HOUR). To group raw rows by hour, convert the other way: toStartOfHour(fromUnixTimestamp64Milli(time)). In the rollups, time is a DateTime (per-minute, per-hour) or a Date (per-day, per-month), so compare directly: time > now() - INTERVAL 7 DAY.

Queries only return data inside your plan's retention window. What happens when you ask for older data depends on how you write the time filter:

• INTERVAL N UNIT, a literal date, or today(): a start time older than your retention fails with err:user:bad_request:query_range_exceeds_retention.
• toIntervalDay(N) or no start time at all: the query runs and quietly returns only the rows inside retention.

For example, time >= now() - INTERVAL 400 DAY fails, while time >= now() - toIntervalDay(400) returns fewer rows with no error. Use INTERVAL N UNIT if you'd rather get an error than a short answer. Retention per plan is on Analytics restrictions and quotas.

Aggregate state columns Copy Chapter

In the rollup tables, read count, spent_credits, total, and similar columns with sum(), never count(), because each row already sums many verifications. You can't read the rollups' latency_avg, latency_p75, and latency_p99 columns, because the -Merge functions they need aren't allowed. Use the raw table instead: avg(latency) and quantile(0.99)(latency). The table pages mark which columns are which.

Api Management Analytics Restrictions And Quotas (`docs/api-management/analytics/restrictions-and-quotas.mdx`) Copy Section

title: Analytics restrictions and quotas
sidebarTitle: "Restrictions and quotas"
sources:

• pkg/clickhouse/query-parser/parser.go
• pkg/clickhouse/query-parser/validation.go
• pkg/clickhouse/query-parser/time_range.go
• pkg/clickhouse/user.go
• pkg/clickhouse/errors.go
• internal/services/analytics/executor.go
• internal/services/analytics/service.go
• svc/api/routes/v2_analytics_get_verifications/handler.go
• web/internal/db/src/schema/clickhouse_workspace_settings.ts
• web/apps/dashboard/lib/limits.ts
• pkg/clickhouse/schema/001_key_verifications_raw_v2.sql
• pkg/clickhouse/schema/006_ratelimits_raw_v2.sql
• svc/api/internal/middleware/errors.go

Every analytics query runs under these limits. Most queries never hit them. When you do, find the error code here to see which limit you hit. For what SQL is allowed, see Analytics query language.

Query shape limits Copy Chapter

These are checked before the query runs. Going over one returns HTTP 400, except nesting depth.

Execution limits Copy Chapter

These apply while the query runs. Hitting one returns HTTP 422.

The 4 MiB response size is the limit people hit first. To stay under it, page with LIMIT and OFFSET, aggregate instead of selecting raw rows, or narrow the time window. NaN and infinity come back as null.

Quota per workspace Copy Chapter

By default, each workspace can run 1,000 queries and 1,800 seconds of total query time per rolling hour. Going over either returns HTTP 429 with err:user:too_many_requests:query_quota_exceeded. Wait for the window to roll over, or contact [email protected] if you need more.

Retention Copy Chapter

Queries only return rows inside your plan's log retention. If your time filter starts earlier than that, the query fails with HTTP 400 and err:user:bad_request:query_range_exceeds_retention, and the detail names the earliest date you can query. A filter written with toIntervalDay(N) instead of INTERVAL N DAY doesn't fail. It just leaves the older rows out. See Working with time.

Plans agreed with sales have their own retention. Your actual value is the Log retention row on Settings > Limits. See Limits.

Each table also has a maximum age, whatever your plan:

• Verifications: raw, per-minute, and per-hour 90 days; per-day 365 days; per-month 3 years.
• Rate limits: raw one month; per-minute 7 days; per-hour 30 days; per-day 100 days; per-month 3 years.

Other errors Copy Chapter

All errors use the standard API error format, and each error's type field links to its page.

Api Management Analytics Troubleshooting (`docs/api-management/analytics/troubleshooting.mdx`) Copy Section

title: Analytics troubleshooting
sidebarTitle: "Troubleshooting"
sources:

• pkg/clickhouse/query-parser/parser.go
• pkg/clickhouse/query-parser/validation.go
• pkg/clickhouse/query-parser/tables.go
• pkg/clickhouse/query-parser/time_range.go
• pkg/clickhouse/errors.go
• pkg/clickhouse/user.go
• internal/services/analytics/service.go
• svc/api/routes/v2_analytics_get_verifications/handler.go

Start with the HTTP status:

• 200 with no rows: the query worked but matched nothing.
• 400: the query was rejected.
• 422 or 429: the query ran and hit a limit.
• 412: analytics isn't turned on.
• 403: the root key is missing a permission.

No rows came back Copy Chapter

Check the time filter. Raw tables store time in milliseconds, so WHERE time >= now() - INTERVAL 1 DAY matches nothing. Write time >= toUnixTimestamp64Milli(now() - INTERVAL 1 DAY) instead. Rollup tables take DateTime or Date values directly.

Check IDs. key_space_id is the keyspace's ks_ ID, not the api_ ID. namespace_id is an rlns_ ID, not the namespace name. Values are case-sensitive, and outcome values are upper case (VALID, not valid).

Check retention. Data older than your plan's log retention is left out, often without an error. See Working with time.

Check the root key. If it has read_analytics for specific keyspaces or namespaces only, rows outside them are left out without an error.

The query was rejected (400) Copy Chapter

The query ran but failed (422 or 429) Copy Chapter

Analytics isn't configured (412) Copy Chapter

err:unkey:data:analytics_not_configured means analytics isn't turned on for your workspace. Email [email protected] with your workspace ID to turn it on. A 503 with analytics_connection_failed is different: analytics was briefly unavailable, so retry with backoff.

Permission denied (403) Copy Chapter

insufficient_permissions names the permission the root key needs: api.*.read_analytics or api.<api_id>.read_analytics for verifications, ratelimit.*.read_analytics or ratelimit.<namespace_id>.read_analytics for rate limits. Grant it under Settings > Root Keys. See Root key permissions.

Numbers that look wrong Copy Chapter

• A rollup total is far too low. You probably wrote count() instead of sum(count). Each rollup row sums many verifications.
• A percentage is null. It divided by zero.
• external_id is empty for many rows. Those keys have no identity. Group by key_id instead, or attach identities when you create keys.

Api Management Authorization Managing Key Permissions (`docs/api-management/authorization/managing-key-permissions.mdx`) Copy Section

title: Managing key roles and permissions
sidebarTitle: "Managing key permissions"
sources:

• svc/api/openapi/spec/paths/v2/keys/createKey/V2KeysCreateKeyRequestBody.yaml
• svc/api/openapi/spec/paths/v2/keys/updateKey/V2KeysUpdateKeyRequestBody.yaml
• svc/api/openapi/spec/paths/v2/keys/setPermissions/V2KeysSetPermissionsRequestBody.yaml
• svc/api/openapi/spec/paths/v2/keys/addPermissions/V2KeysAddPermissionsRequestBody.yaml
• svc/api/openapi/spec/paths/v2/keys/removePermissions/V2KeysRemovePermissionsRequestBody.yaml
• svc/api/openapi/spec/paths/v2/keys/addRoles/V2KeysAddRolesRequestBody.yaml
• svc/api/openapi/spec/paths/v2/keys/removeRoles/V2KeysRemoveRolesRequestBody.yaml
• svc/api/openapi/spec/paths/v2/keys/setRoles/V2KeysSetRolesRequestBody.yaml
• svc/api/routes/v2_keys_create_key/handler.go
• svc/api/routes/v2_keys_update_key/handler.go
• svc/api/routes/v2_keys_add_permissions/handler.go
• svc/api/routes/v2_keys_remove_permissions/handler.go
• svc/api/routes/v2_keys_set_permissions/handler.go
• svc/api/routes/v2_keys_add_roles/handler.go
• svc/api/routes/v2_keys_remove_roles/handler.go
• svc/api/routes/v2_keys_set_roles/handler.go
• web/apps/dashboard/components/api-keys-table/components/actions/keys-table-action.popover.constants.tsx

import RootKeyPrereq from "/snippets/root-key-prereq.mdx";

Change the roles and permissions on a key at any time. Set them when you create the key, replace them with keys.updateKey, or add and remove them with six dedicated endpoints. Changes take about 10 seconds to reach verification. Verifying keys describes that timing.

curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "api_...",
    "roles": ["editor"],
    "permissions": ["reports.export"]
  }'

curl -X POST https://api.unkey.com/v2/keys.addPermissions \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "keyId": "key_...", "permissions": ["documents.delete"] }'

expression    -> andExpression (OR andExpression)*
andExpression -> primary (AND primary)*
primary       -> PERMISSION | "(" expression ")"

curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "key": "sk_live_...", "permissions": "(admin OR editor) AND billing:view" }'

const { data } = await unkey.keys.verifyKey({ key: incomingKey });
if (!data.valid) {
  return deny(data.code);
}

const permissions = data.permissions ?? [];
const document = await db.documents.find(documentId);

const canDelete =
  permissions.includes("admin") ||
  (permissions.includes("documents.delete") && document.ownerId === data.identity?.externalId);

curl -X POST https://api.unkey.com/v2/permissions.createPermission \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Read documents", "slug": "documents.read", "description": "List and fetch documents" }'

curl -X POST https://api.unkey.com/v2/permissions.createRole \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "editor",
    "description": "Read and write documents",
    "permissions": ["documents.read", "documents.write"]
  }'

curl -X POST https://api.unkey.com/v2/permissions.setRolePermissions \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "role": "editor", "permissions": ["documents.read", "documents.write", "documents.delete"] }'

curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "api_...",
    "ratelimits": [
      { "name": "reads",  "limit": 1000, "duration": 60000, "autoApply": false },
      { "name": "writes", "limit": 100,  "duration": 60000, "autoApply": false }
    ]
  }'

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

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

export async function verifyFor(key: string, method: string) {
  const name = method === "GET" ? "reads" : "writes";
  const result = await unkey.keys.verifyKey({ key, ratelimits: [{ name }] });
  return result.data;
}

curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "key": "sk_live_...", "ratelimits": [{ "name": "reads", "cost": 10 }] }'

const rl = await unkey.ratelimit.limit({
  namespace: "POST /v1/items",
  identifier: userId,
  limit: 100,
  duration: 60_000,
  cost: 1,
});
if (!rl.data.success) {
  return Response.json({ error: "rate limited" }, { status: 429 });
}

/* Detailed source-code truncated for AI context efficiency. */

from typing import Annotated

from fastapi import Depends, FastAPI
from unkey.py import models

from .auth import require_key

app = FastAPI()


@app.get("/items")
def list_items(verification: Annotated[models.V2KeysVerifyKeyResponseData, Depends(require_key())]):
    owner = verification.identity.external_id if verification.identity else None
    return {"items": [], "owner": owner, "credits_left": verification.credits}


@app.get("/reports")
def reports(verification: Annotated[models.V2KeysVerifyKeyResponseData, Depends(require_key("reports.read"))]):
    return {"reports": [], "key": verification.key_id}

/* Detailed source-code truncated for AI context efficiency. */

"github.com/unkeyed/sdks/api/go/v3/models/components"

```go Gin
package auth

import (
	"github.com/gin-gonic/gin"
)

func (v *Verifier) Gin(permissions string) gin.HandlerFunc {
	return func(c *gin.Context) {
		res := v.Verify(c.Request.Context(), c.GetHeader("Authorization"), permissions)
		if res.Err != nil {
			c.AbortWithStatusJSON(res.Status, gin.H{"error": "authentication unavailable"})
			return
		}
		if !res.Data.Valid {
			c.AbortWithStatusJSON(res.Status, gin.H{"error": res.Reason})
			return
		}
		c.Set("unkey", res.Data)
		c.Next()
	}
}

package auth

import (
	"github.com/labstack/echo/v4"
)

func (v *Verifier) Echo(permissions string) echo.MiddlewareFunc {
	return func(next echo.HandlerFunc) echo.HandlerFunc {
		return func(c echo.Context) error {
			res := v.Verify(c.Request().Context(), c.Request().Header.Get("Authorization"), permissions)
			if res.Err != nil {
				return c.JSON(res.Status, map[string]string{"error": "authentication unavailable"})
			}
			if !res.Data.Valid {
				return c.JSON(res.Status, map[string]string{"error": res.Reason})
			}
			c.Set("unkey", res.Data)
			return next(c)
		}
	}
}

verifier := auth.New(os.Getenv("UNKEY_ROOT_KEY"))

// net/http
mux := http.NewServeMux()
mux.Handle("/items", verifier.Middleware("")(http.HandlerFunc(listItems)))
mux.Handle("/admin", verifier.Middleware("admin.read")(http.HandlerFunc(admin)))

// Gin
r := gin.Default()
r.GET("/items", verifier.Gin(""), func(c *gin.Context) {
	data := c.MustGet("unkey").(components.V2KeysVerifyKeyResponseData)
	c.JSON(200, gin.H{"keyId": data.KeyID})
})

// Echo
e := echo.New()
e.GET("/items", listItemsEcho, verifier.Echo(""))

curl -X POST https://api.unkey.com/v2/identities.createIdentity \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user_123",
    "meta": { "plan": "free" },
    "ratelimits": [
      { "name": "requests", "limit": 100, "duration": 60000, "autoApply": true }
    ]
  }'

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

const result = await unkey.keys.verifyKey({ key });
const rl = result.data.ratelimits?.find((r) => r.name === "requests");
const headers = rl
  ? {
      "X-RateLimit-Limit": String(rl.limit),
      "X-RateLimit-Remaining": String(rl.remaining),
      "X-RateLimit-Reset": String(rl.reset),
    }
  : {};
if (!result.data.valid) {
  return Response.json({ error: result.data.code }, { status: result.data.code === "RATE_LIMITED" ? 429 : 401, headers });
}

curl -X POST https://api.unkey.com/v2/ratelimit.setOverride \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "namespace": "api.requests", "identifier": "user_123", "limit": 1000, "duration": 60000 }'

export const PLANS = {
  free: {
    ratelimits: [{ name: "requests", limit: 60, duration: 60_000, autoApply: true }],
    credits: { remaining: 1_000, refill: { interval: "monthly" as const, amount: 1_000, refillDay: 1 } },
    permissions: ["items.read"],
  },
  pro: {
    ratelimits: [{ name: "requests", limit: 600, duration: 60_000, autoApply: true }],
    credits: { remaining: 100_000, refill: { interval: "monthly" as const, amount: 100_000, refillDay: 1 } },
    permissions: ["items.read", "items.write", "exports.create"],
  },
  enterprise: {
    ratelimits: [{ name: "requests", limit: 6_000, duration: 60_000, autoApply: true }],
    credits: null,
    permissions: ["items.read", "items.write", "exports.create", "webhooks.manage"],
  },
};

export type Plan = keyof typeof PLANS;

import { Unkey } from "@unkey/api";
import { PLANS, type Plan } from "./plans";

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

export async function createKeyFor(customerId: string, plan: Plan) {
  const tier = PLANS[plan];
  const created = await unkey.keys.createKey({
    apiId: process.env.UNKEY_API_ID ?? "",
    externalId: customerId,
    meta: { plan },
    ratelimits: tier.ratelimits,
    permissions: tier.permissions,
    ...(tier.credits ? { credits: tier.credits } : {}),
  });
  return created.data; // key (plaintext, show once) and keyId
}

const result = await unkey.keys.verifyKey({ key, permissions: "exports.create" });
if (!result.data.valid) {
  // INSUFFICIENT_PERMISSIONS here means "not on a plan that includes exports"
  return Response.json({ error: result.data.code }, { status: result.data.code === "INSUFFICIENT_PERMISSIONS" ? 403 : 401 });
}
const plan = (result.data.meta as { plan?: string } | undefined)?.plan ?? "free";
const pageSize = plan === "enterprise" ? 1000 : 100;

curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "api_...",
    "externalId": "customer_123",
    "credits": {
      "remaining": 10000,
      "refill": { "interval": "monthly", "amount": 10000, "refillDay": 1 }
    }
  }'

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

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

const COST: Record<string, number> = {
  "GET /v1/status": 0,
  "GET /v1/items": 1,
  "POST /v1/export": 50,
};

export async function meter(key: string, route: string) {
  const result = await unkey.keys.verifyKey({
    key,
    credits: { cost: COST[route] ?? 1 },
    tags: [`route=${route}`],
  });

  if (!result.data.valid) {
    if (result.data.code === "USAGE_EXCEEDED") {
      // data.credits is the unchanged balance; nothing was deducted.
      return { ok: false as const, status: 402, remaining: result.data.credits ?? 0 };
    }
    return { ok: false as const, status: 401, remaining: result.data.credits };
  }
  // data.credits is the balance after this call. Surface it so clients can plan.
  return { ok: true as const, remaining: result.data.credits, customer: result.data.identity?.externalId };
}

Workspace
└── Keyspace (api_..., ks_...)
    ├── defaults: prefix, bytes, encrypted storage, IP allow list, delete protection
    └── Key (key_...)
        ├── enabled, expires, credits, rate limits, permissions, roles, meta
        └── Identity (externalId)          shared rate limits and meta across keys

Root key (unkey_...)  authenticates your calls; permissions name keyspaces by api_ id

Then create a keyspace, which holds your keys. Use **Keyspaces (APIs)** in the dashboard, or `apis.createApi`:

```bash create a keyspace
curl -X POST https://api.unkey.com/v2/apis.createApi \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-api" }'
```

Keep the `data.apiId` from the response. You need it to create keys. See [Root keys](/platform/root-keys/overview) for more on root keys.

```bash
bun add @unkey/api
```

<CodeGroup>
```bash curl
curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "apiId": "api_...", "prefix": "sk_live", "externalId": "user_123", "meta": { "plan": "free" } }'
```
```ts TypeScript
import { Unkey } from "@unkey/api";

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

const created = await unkey.keys.createKey({
  apiId: process.env.UNKEY_API_ID ?? "",
  prefix: "sk_live",
  externalId: "user_123",
  meta: { plan: "free" },
});
// created.data.key is the plaintext, created.data.keyId the handle you keep
```
</CodeGroup>

Every field is described in [Creating keys](/api-management/keys/creating-keys).

```

```bash
    bun run server.ts
    curl http://localhost:3000/items -H "Authorization: Bearer sk_live_..."
    ```
  </Step>
  <Step title="Handle the outcome codes">
    `keys.verifyKey` returns HTTP 200 for every outcome. Check `data.valid`, then `data.code` for the reason, and return the matching status from your API:

    | `data.code` | Meaning | Return |
    | --- | --- | --- |
    | `VALID` | Every check passed. | continue |
    | `NOT_FOUND` | No such key, or your root key may not verify this keyspace. | 401 |
    | `DISABLED` | The key was disabled. | 401 |
    | `EXPIRED` | The key's expiry passed. | 401 |
    | `FORBIDDEN` | Client IP not on the keyspace allow list, or the workspace is disabled. | 403 |
    | `INSUFFICIENT_PERMISSIONS` | The `permissions` query was not satisfied. | 403 |
    | `RATE_LIMITED` | A <Tooltip tip="Here: limits enforced by keys.verifyKey on a key or identity, or by the standalone ratelimit API. Not a Compute gateway policy.">rate limit</Tooltip> on the key or its identity was exceeded. | 429 |
    | `USAGE_EXCEEDED` | The key has no credits left. | 402 or 429 |

    Remaining credits are in `data.credits`, and each checked rate limit is in `data.ratelimits` with `remaining` and `reset`. The call only fails with an HTTP error (which the SDKs throw) when the call itself is wrong, such as a bad root key or a malformed body. See [Verifying keys](/api-management/keys/verifying-keys) for every field.
  </Step>
  <Step title="Next steps">
    <Columns cols={2}>
      <Card title="Verifying keys" href="/api-management/keys/verifying-keys" icon="key">Every request field, the order of checks, and every response field.</Card>
      <Card title="Credits and refill" href="/api-management/keys/credits-and-refill" icon="coins">Meter usage per key and refill balances on a schedule.</Card>
      <Card title="Cookbook" href="/api-management/cookbook/index" icon="book">Copy-ready recipes for rate limits, billing, and subscription tiers.</Card>
    </Columns>
  </Step>
</Steps>

---

### Api Management Guides Cloudflare Workers (`docs/api-management/guides/cloudflare-workers.mdx`)

---
title: Cloudflare Workers guide
sidebarTitle: "Cloudflare Workers"
sources:
  - svc/api/openapi/spec/paths/v2/apis/createApi/V2ApisCreateApiRequestBody.yaml
  - svc/api/openapi/spec/paths/v2/apis/createApi/V2ApisCreateApiResponseData.yaml
  - pkg/rbac/permissions.go
  - svc/api/openapi/spec/paths/v2/keys/createKey/V2KeysCreateKeyRequestBody.yaml
  - svc/api/openapi/spec/paths/v2/keys/createKey/V2KeysCreateKeyResponseData.yaml
  - svc/api/openapi/spec/paths/v2/keys/verifyKey/V2KeysVerifyKeyRequestBody.yaml
  - svc/api/openapi/spec/paths/v2/keys/verifyKey/V2KeysVerifyKeyResponseData.yaml
  - web/internal/api/src/sdk/keys.ts
  - web/internal/api/src/models/components/v2keysverifykeyresponsedata.ts
  - https://github.com/unkeyed/sdks/blob/3bb124498270d8aff36e358dc2e0010e9991869a/api/ts/README.md
---
import RootKeyPrereq from "/snippets/root-key-prereq.mdx";
import { versions } from "/snippets/versions.mdx";

Protect a Cloudflare Worker with API keys. The Worker's `fetch` handler calls `keys.verifyKey` on each request. Store the root key as a Worker secret, never in `wrangler.toml`.

<RootKeyPrereq />

<Steps titleSize="h3">
  <Step title="Create a root key and a keyspace">
    In the dashboard, go to **Settings > Root Keys** and create a root key with `api.*.create_api`, `api.*.create_key`, and `api.*.verify_key`. Export it as `UNKEY_ROOT_KEY` in your shell for the `curl` commands. You'll store it as a Worker secret in step 2. Never send it to a browser or mobile app.

    Then create a keyspace, which holds your keys. Use **Keyspaces (APIs)** in the dashboard, or `apis.createApi`:

    ```bash create a keyspace
    curl -X POST https://api.unkey.com/v2/apis.createApi \
      -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "name": "my-api" }'
    ```

    Keep the `data.apiId` from the response. You need it to create keys. See [Root keys](/platform/root-keys/overview) for more on root keys.
  </Step>
  <Step title="Install the SDK and store the root key">
    `@unkey/api` (version {versions.tsApi}) runs on Workers with no polyfills.

    ```bash
    npm install @unkey/api
    npx wrangler secret put UNKEY_ROOT_KEY
    ```

    Your code reads it as `env.UNKEY_ROOT_KEY`. If your Worker also creates keys, add the keyspace ID from step 1 as an `UNKEY_API_ID` variable in `wrangler.toml`. It isn't secret.
  </Step>
  <Step title="Create a key for a user">
    Create a key when a user signs up or asks for one. `externalId` links the key to the user, so verification tells you who's calling. `meta` comes back on every verification. You get `data.key` only once: show it to the user and store only `data.keyId`.

    Workers have no `process.env`, so read the secret and keyspace ID from the handler's `env` argument.

    <CodeGroup>
    ```bash curl
    curl -X POST https://api.unkey.com/v2/keys.createKey \
      -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "apiId": "api_...", "prefix": "sk_live", "externalId": "user_123", "meta": { "plan": "free" } }'
    ```
    ```ts src/issue.ts
    import { Unkey } from "@unkey/api";

    interface Env {
      UNKEY_ROOT_KEY: string;
      UNKEY_API_ID: string;
    }

    // Call this from a route your own session check already protects.
    export async function issueKey(env: Env, userId: string): Promise<string> {
      const unkey = new Unkey({ rootKey: env.UNKEY_ROOT_KEY });

      const created = await unkey.keys.createKey({
        apiId: env.UNKEY_API_ID,
        prefix: "sk_live",
        externalId: userId,
        meta: { plan: "free" },
      });
      // created.data.key is the plaintext, created.data.keyId the handle you keep
      return created.data.key;
    }
    ```
    </CodeGroup>

    Every field is described in [Creating keys](/api-management/keys/creating-keys).
  </Step>
  <Step title="Verify the key in the fetch handler">
    `env` is only available inside the handler, so create the client there. The code below creates it once and reuses it.

    ```
/* Detailed source-code truncated for AI context efficiency. */

```bash
npx wrangler dev
curl http://localhost:8787/ -H "Authorization: Bearer sk_live_..."
```

Prefer a router? The [Hono guide](/api-management/guides/hono) runs unchanged on Workers. Read the root key from `c.env.UNKEY_ROOT_KEY` instead of `process.env`.

| `data.code` | Meaning | Return |
| --- | --- | --- |
| `VALID` | Every check passed. | continue |
| `NOT_FOUND` | No such key, or your root key may not verify this keyspace. | 401 |
| `DISABLED` | The key was disabled. | 401 |
| `EXPIRED` | The key's expiry passed. | 401 |
| `FORBIDDEN` | Client IP not on the keyspace allow list, or the workspace is disabled. | 403 |
| `INSUFFICIENT_PERMISSIONS` | The `permissions` query was not satisfied. | 403 |
| `RATE_LIMITED` | A <Tooltip tip="Here: limits enforced by keys.verifyKey on a key or identity, or by the standalone ratelimit API. Not a Compute gateway policy.">rate limit</Tooltip> on the key or its identity was exceeded. | 429 |
| `USAGE_EXCEEDED` | The key has no credits left. | 402 or 429 |

Remaining credits are in `data.credits`, and each checked rate limit is in `data.ratelimits` with `remaining` and `reset`. The call only fails with an HTTP error (which the SDKs throw) when the call itself is wrong, such as a bad root key or a malformed body. See [Verifying keys](/api-management/keys/verifying-keys) for every field.

Then create a keyspace, which holds your keys. Use **Keyspaces (APIs)** in the dashboard, or `apis.createApi`:

```bash create a keyspace
curl -X POST https://api.unkey.com/v2/apis.createApi \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-api" }'
```

Keep the `data.apiId` from the response. You need it to create keys. See [Root keys](/platform/root-keys/overview) for more on root keys.

<CodeGroup>
```bash npm
npm install @unkey/api express
```
```bash pnpm
pnpm add @unkey/api express
```
</CodeGroup>

<CodeGroup>
```bash curl
curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "apiId": "api_...", "prefix": "sk_live", "externalId": "user_123", "meta": { "plan": "free" } }'
```
```ts TypeScript
import { Unkey } from "@unkey/api";

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

const created = await unkey.keys.createKey({
  apiId: process.env.UNKEY_API_ID ?? "",
  prefix: "sk_live",
  externalId: "user_123",
  meta: { plan: "free" },
});
// created.data.key is the plaintext, created.data.keyId the handle you keep
```
</CodeGroup>

Every field is described in [Creating keys](/api-management/keys/creating-keys).

Keep `next()` outside the `try`. Otherwise an error in a route handler is caught here and answered as a 503 authentication failure.

```

```ts src/server.ts
    import express from "express";
    import { requireKey } from "./unkey";

    const app = express();

    app.get("/items", requireKey(), (_req, res) => {
      res.json({ items: [], owner: res.locals.unkey.identity?.externalId });
    });

    app.post("/items", requireKey("items.write"), (_req, res) => {
      res.status(201).json({ ok: true });
    });

    app.listen(3000);
    ```

    ```bash
    curl http://localhost:3000/items -H "Authorization: Bearer sk_live_..."
    ```
  </Step>
  <Step title="Handle the outcome codes">
    `keys.verifyKey` returns HTTP 200 for every outcome. Check `data.valid`, then `data.code` for the reason, and return the matching status from your API:

    | `data.code` | Meaning | Return |
    | --- | --- | --- |
    | `VALID` | Every check passed. | continue |
    | `NOT_FOUND` | No such key, or your root key may not verify this keyspace. | 401 |
    | `DISABLED` | The key was disabled. | 401 |
    | `EXPIRED` | The key's expiry passed. | 401 |
    | `FORBIDDEN` | Client IP not on the keyspace allow list, or the workspace is disabled. | 403 |
    | `INSUFFICIENT_PERMISSIONS` | The `permissions` query was not satisfied. | 403 |
    | `RATE_LIMITED` | A <Tooltip tip="Here: limits enforced by keys.verifyKey on a key or identity, or by the standalone ratelimit API. Not a Compute gateway policy.">rate limit</Tooltip> on the key or its identity was exceeded. | 429 |
    | `USAGE_EXCEEDED` | The key has no credits left. | 402 or 429 |

    Remaining credits are in `data.credits`, and each checked rate limit is in `data.ratelimits` with `remaining` and `reset`. The call only fails with an HTTP error (which the SDKs throw) when the call itself is wrong, such as a bad root key or a malformed body. See [Verifying keys](/api-management/keys/verifying-keys) for every field.
  </Step>
  <Step title="Next steps">
    <Columns cols={2}>
      <Card title="Verifying keys" href="/api-management/keys/verifying-keys" icon="key">Every request field, the order of checks, and every response field.</Card>
      <Card title="Credits and refill" href="/api-management/keys/credits-and-refill" icon="coins">Meter usage per key and refill balances on a schedule.</Card>
      <Card title="Cookbook" href="/api-management/cookbook/index" icon="book">Copy-ready recipes for rate limits, billing, and subscription tiers.</Card>
    </Columns>
  </Step>
</Steps>

---

### Api Management Guides Go (`docs/api-management/guides/go.mdx`)

---
title: Go guide
sidebarTitle: "Go"
sources:
  - svc/api/openapi/spec/paths/v2/apis/createApi/V2ApisCreateApiRequestBody.yaml
  - svc/api/openapi/spec/paths/v2/apis/createApi/V2ApisCreateApiResponseData.yaml
  - pkg/rbac/permissions.go
  - svc/api/openapi/spec/paths/v2/keys/createKey/V2KeysCreateKeyRequestBody.yaml
  - svc/api/openapi/spec/paths/v2/keys/createKey/V2KeysCreateKeyResponseData.yaml
  - svc/api/openapi/spec/paths/v2/keys/verifyKey/V2KeysVerifyKeyRequestBody.yaml
  - svc/api/openapi/spec/paths/v2/keys/verifyKey/V2KeysVerifyKeyResponseData.yaml
  - https://github.com/unkeyed/sdks/blob/3bb124498270d8aff36e358dc2e0010e9991869a/api/go/v3/keys.go
  - https://github.com/unkeyed/sdks/blob/3bb124498270d8aff36e358dc2e0010e9991869a/api/go/v3/unkey.go
  - https://github.com/unkeyed/sdks/blob/3bb124498270d8aff36e358dc2e0010e9991869a/api/go/v3/models/components/v2keysverifykeyresponsedata.go
  - https://github.com/unkeyed/sdks/blob/3bb124498270d8aff36e358dc2e0010e9991869a/api/go/v3/README.md
---
import RootKeyPrereq from "/snippets/root-key-prereq.mdx";
import { versions } from "/snippets/versions.mdx";

Protect a Go HTTP server with API keys, using the official Go SDK, `github.com/unkeyed/sdks/api/go/v3` (version {versions.goSdk}). For ready-made middleware for `net/http`, Gin, and Echo, see [Go middleware](/api-management/cookbook/go-middleware).

<RootKeyPrereq />

<Steps titleSize="h3">
  <Step title="Create a root key and a keyspace">
    In the dashboard, go to **Settings > Root Keys** and create a root key with `api.*.create_api`, `api.*.create_key`, and `api.*.verify_key`. Put it in your server's `UNKEY_ROOT_KEY` environment variable. Never send it to a browser or mobile app.

    Then create a keyspace, which holds your keys. Use **Keyspaces (APIs)** in the dashboard, or `apis.createApi`:

    ```bash create a keyspace
    curl -X POST https://api.unkey.com/v2/apis.createApi \
      -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "name": "my-api" }'
    ```

    Keep the `data.apiId` from the response. You need it to create keys. See [Root keys](/platform/root-keys/overview) for more on root keys.
  </Step>
  <Step title="Install the SDK">
    ```bash
    go get github.com/unkeyed/sdks/api/go/v3
    ```

    Create the client once with `unkey.New(unkey.WithSecurity(rootKey))`. It's safe to share across goroutines.
  </Step>
  <Step title="Create a key for a user">
    Create a key from your backend when a user signs up or asks for one. `externalId` links the key to the user, so verification tells you who's calling. `meta` comes back on every verification. You get `data.key` only once: show it to the user and store only `data.keyId`.

    <CodeGroup>
    ```bash curl
    curl -X POST https://api.unkey.com/v2/keys.createKey \
      -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "apiId": "api_...", "prefix": "sk_live", "externalId": "user_123", "meta": { "plan": "free" } }'
    ```
    ```go Go
    package main

    import (
    	"context"
    	"fmt"
    	"log"
    	"os"

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

    func main() {
    	client := unkey.New(unkey.WithSecurity(os.Getenv("UNKEY_ROOT_KEY")))

    	prefix := "sk_live"
    	externalID := "user_123"
    	res, err := client.Keys.CreateKey(context.Background(), components.V2KeysCreateKeyRequestBody{
    		APIID:      os.Getenv("UNKEY_API_ID"),
    		Prefix:     &prefix,
    		ExternalID: &externalID,
    		Meta:       map[string]any{"plan": "free"},
    	})
    	if err != nil {
    		log.Fatal(err)
    	}
    	if res.V2KeysCreateKeyResponseBody == nil {
    		log.Fatal("unkey: empty response body")
    	}
    	// res.V2KeysCreateKeyResponseBody.Data.Key is the plaintext, Data.KeyID the handle you keep
    	fmt.Println(res.V2KeysCreateKeyResponseBody.Data.KeyID)
    }
    ```
    </CodeGroup>

    Every field is described in [Creating keys](/api-management/keys/creating-keys).
  </Step>
  <Step title="Verify the key in a handler">
    The answer is in `res.V2KeysVerifyKeyResponseBody.Data.Valid` and `.Data.Code`. `V2KeysVerifyKeyResponseBody` is a pointer, so check it for `nil` even when `err` is `nil`. Use the `components.Code*` constants to switch on the outcome. An `error` means the call itself failed, not that the key is invalid.

    ```
/* Detailed source-code truncated for AI context efficiency. */

```bash
go run . &
curl http://localhost:3000/items -H "Authorization: Bearer sk_live_..."
```

| `data.code` | Meaning | Return |
| --- | --- | --- |
| `VALID` | Every check passed. | continue |
| `NOT_FOUND` | No such key, or your root key may not verify this keyspace. | 401 |
| `DISABLED` | The key was disabled. | 401 |
| `EXPIRED` | The key's expiry passed. | 401 |
| `FORBIDDEN` | Client IP not on the keyspace allow list, or the workspace is disabled. | 403 |
| `INSUFFICIENT_PERMISSIONS` | The `permissions` query was not satisfied. | 403 |
| `RATE_LIMITED` | A <Tooltip tip="Here: limits enforced by keys.verifyKey on a key or identity, or by the standalone ratelimit API. Not a Compute gateway policy.">rate limit</Tooltip> on the key or its identity was exceeded. | 429 |
| `USAGE_EXCEEDED` | The key has no credits left. | 402 or 429 |

Remaining credits are in `data.credits`, and each checked rate limit is in `data.ratelimits` with `remaining` and `reset`. The call only fails with an HTTP error (which the SDKs throw) when the call itself is wrong, such as a bad root key or a malformed body. See [Verifying keys](/api-management/keys/verifying-keys) for every field.

Then create a keyspace, which holds your keys. Use **Keyspaces (APIs)** in the dashboard, or `apis.createApi`:

```bash create a keyspace
curl -X POST https://api.unkey.com/v2/apis.createApi \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-api" }'
```

Keep the `data.apiId` from the response. You need it to create keys. See [Root keys](/platform/root-keys/overview) for more on root keys.

<CodeGroup>
```bash npm
npm install hono @unkey/hono @unkey/api
```
```bash bun
bun add hono @unkey/hono @unkey/api
```
</CodeGroup>

<CodeGroup>
```bash curl
curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "apiId": "api_...", "prefix": "sk_live", "externalId": "user_123", "meta": { "plan": "free" } }'
```
```ts TypeScript
import { Unkey } from "@unkey/api";

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

const created = await unkey.keys.createKey({
  apiId: process.env.UNKEY_API_ID ?? "",
  prefix: "sk_live",
  externalId: "user_123",
  meta: { plan: "free" },
});
// created.data.key is the plaintext, created.data.keyId the handle you keep
```
</CodeGroup>

Every field is described in [Creating keys](/api-management/keys/creating-keys).

`onError` only runs for unexpected responses, such as a 502 from a proxy. A rejected root key, a throttled request, a 500, or a network failure is thrown instead, so catch those in Hono's `app.onError` if you want one response for every authentication failure.

<CodeGroup>
```ts src/index.ts (@unkey/hono)
import { Hono } from "hono";
import { type UnkeyContext, unkey } from "@unkey/hono";

const app = new Hono<{ Variables: { unkey: UnkeyContext } }>();

app.use(
  "/items/*",
  unkey({
    rootKey: process.env.UNKEY_ROOT_KEY ?? "",
    handleInvalidKey: (c) => c.json({ error: "invalid API key" }, 401),
    onError: (c, err) => {
      console.error("unkey", err.message);
      return c.json({ error: "authentication unavailable" }, 503);
    },
  }),
);

app.get("/items/list", (c) => {
  const verification = c.get("unkey");
  return c.json({ items: [], owner: verification.data.identity?.externalId });
});

export default app;
```
```

</CodeGroup>

    Keep `next()` outside the `try`. Otherwise an error in a route handler is caught here and answered as an authentication failure.

    The middleware also takes `permissions` (a permission query every key must pass), `tags`, and `getKey` (for keys sent somewhere other than the `Authorization` header).
  </Step>
  <Step title="Handle the outcome codes">
    `keys.verifyKey` returns HTTP 200 for every outcome. Check `data.valid`, then `data.code` for the reason, and return the matching status from your API:

    | `data.code` | Meaning | Return |
    | --- | --- | --- |
    | `VALID` | Every check passed. | continue |
    | `NOT_FOUND` | No such key, or your root key may not verify this keyspace. | 401 |
    | `DISABLED` | The key was disabled. | 401 |
    | `EXPIRED` | The key's expiry passed. | 401 |
    | `FORBIDDEN` | Client IP not on the keyspace allow list, or the workspace is disabled. | 403 |
    | `INSUFFICIENT_PERMISSIONS` | The `permissions` query was not satisfied. | 403 |
    | `RATE_LIMITED` | A <Tooltip tip="Here: limits enforced by keys.verifyKey on a key or identity, or by the standalone ratelimit API. Not a Compute gateway policy.">rate limit</Tooltip> on the key or its identity was exceeded. | 429 |
    | `USAGE_EXCEEDED` | The key has no credits left. | 402 or 429 |

    Remaining credits are in `data.credits`, and each checked rate limit is in `data.ratelimits` with `remaining` and `reset`. The call only fails with an HTTP error (which the SDKs throw) when the call itself is wrong, such as a bad root key or a malformed body. See [Verifying keys](/api-management/keys/verifying-keys) for every field.
  </Step>
  <Step title="Next steps">
    <Columns cols={2}>
      <Card title="Verifying keys" href="/api-management/keys/verifying-keys" icon="key">Every request field, the order of checks, and every response field.</Card>
      <Card title="Credits and refill" href="/api-management/keys/credits-and-refill" icon="coins">Meter usage per key and refill balances on a schedule.</Card>
      <Card title="Cookbook" href="/api-management/cookbook/index" icon="book">Copy-ready recipes for rate limits, billing, and subscription tiers.</Card>
    </Columns>
  </Step>
</Steps>

---

### Api Management Guides Nextjs (`docs/api-management/guides/nextjs.mdx`)

---
title: Next.js guide
sidebarTitle: "Next.js"
sources:
  - svc/api/openapi/spec/paths/v2/apis/createApi/V2ApisCreateApiRequestBody.yaml
  - svc/api/openapi/spec/paths/v2/apis/createApi/V2ApisCreateApiResponseData.yaml
  - pkg/rbac/permissions.go
  - svc/api/openapi/spec/paths/v2/keys/createKey/V2KeysCreateKeyRequestBody.yaml
  - svc/api/openapi/spec/paths/v2/keys/createKey/V2KeysCreateKeyResponseData.yaml
  - svc/api/openapi/spec/paths/v2/keys/verifyKey/V2KeysVerifyKeyRequestBody.yaml
  - svc/api/openapi/spec/paths/v2/keys/verifyKey/V2KeysVerifyKeyResponseData.yaml
  - web/internal/api/src/sdk/keys.ts
  - web/internal/api/src/models/components/v2keysverifykeyresponsedata.ts
  - https://github.com/unkeyed/sdks/blob/3bb124498270d8aff36e358dc2e0010e9991869a/api/ts/README.md
  - https://github.com/unkeyed/sdks/blob/3bb124498270d8aff36e358dc2e0010e9991869a/nextjs/README.md
---
import RootKeyPrereq from "/snippets/root-key-prereq.mdx";
import { versions } from "/snippets/versions.mdx";

Protect a Next.js App Router route handler with API keys. Your server creates keys for users, and every request to the route is checked with `keys.verifyKey` before your handler runs. Verification needs your root key, so do it in route handlers or server actions, never in client components.

<RootKeyPrereq />

<Steps titleSize="h3">
  <Step title="Create a root key and a keyspace">
    In the dashboard, go to **Settings > Root Keys** and create a root key with `api.*.create_api`, `api.*.create_key`, and `api.*.verify_key`. Put it in your server's `UNKEY_ROOT_KEY` environment variable. Never send it to a browser or mobile app.

    Then create a keyspace, which holds your keys. Use **Keyspaces (APIs)** in the dashboard, or `apis.createApi`:

    ```bash create a keyspace
    curl -X POST https://api.unkey.com/v2/apis.createApi \
      -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "name": "my-api" }'
    ```

    Keep the `data.apiId` from the response. You need it to create keys. See [Root keys](/platform/root-keys/overview) for more on root keys.
  </Step>
  <Step title="Install the SDK">
    `@unkey/api` (version {versions.tsApi}) is the client for the whole API. `@unkey/nextjs` (version {versions.tsNextjs}) wraps a route handler and verifies for you. You only need it for the wrapper in step 4.

    <CodeGroup>
    ```bash npm
    npm install @unkey/api @unkey/nextjs
    ```
    ```bash pnpm
    pnpm add @unkey/api @unkey/nextjs
    ```
    ```bash bun
    bun add @unkey/api @unkey/nextjs
    ```
    </CodeGroup>
  </Step>
  <Step title="Create a key for a user">
    Create a key from your backend when a user signs up or asks for one. `externalId` links the key to the user, so verification tells you who's calling. `meta` comes back on every verification. You get `data.key` only once: show it to the user and store only `data.keyId`.

    <CodeGroup>
    ```bash curl
    curl -X POST https://api.unkey.com/v2/keys.createKey \
      -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "apiId": "api_...", "prefix": "sk_live", "externalId": "user_123", "meta": { "plan": "free" } }'
    ```
    ```ts TypeScript
    import { Unkey } from "@unkey/api";

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

    const created = await unkey.keys.createKey({
      apiId: process.env.UNKEY_API_ID ?? "",
      prefix: "sk_live",
      externalId: "user_123",
      meta: { plan: "free" },
    });
    // created.data.key is the plaintext, created.data.keyId the handle you keep
    ```
    </CodeGroup>

    Every field is described in [Creating keys](/api-management/keys/creating-keys).
  </Step>
  <Step title="Verify the key in a route handler">
    The first handler calls `keys.verifyKey` directly, so you control the response. The second uses `withUnkey`, which reads the bearer token from the `Authorization` header, <Tooltip tip="Here: keys.verifyKey checking a key your user presented. Not domain verification and not the gateway policy.">verifies</Tooltip> it, and puts the result in `req.unkey`. Pass `handleInvalidKey` to choose the response for a bad key.

    <CodeGroup>
    ```
/* Detailed source-code truncated for AI context efficiency. */

```ts app/api/items/route.ts (@unkey/nextjs)
import { withUnkey } from "@unkey/nextjs";
import { NextResponse } from "next/server";

export const GET = withUnkey(
  async (req) => {
    // req.unkey holds the verification response; the key is already valid here
    return NextResponse.json({ items: [], keyId: req.unkey?.data.keyId });
  },
  {
    rootKey: process.env.UNKEY_ROOT_KEY ?? "",
    handleInvalidKey: () => NextResponse.json({ error: "invalid API key" }, { status: 401 }),
    onError: (_req, err) => {
      console.error("unkey", err.message);
      return NextResponse.json({ error: "authentication unavailable" }, { status: 503 });
    },
  },
);
```
</CodeGroup>

<Warning>
`withUnkey` only calls `onError` for unexpected responses, such as a 502 from a proxy. A rejected root key, a throttled request, a 500, or a network failure is thrown instead, so your route fails with an unhandled error rather than a 503. The hand-written version catches all of these and returns 503.
</Warning>

Test it with the key from step 3:

```bash
curl http://localhost:3000/api/items -H "Authorization: Bearer sk_live_..."
```

| `data.code` | Meaning | Return |
| --- | --- | --- |
| `VALID` | Every check passed. | continue |
| `NOT_FOUND` | No such key, or your root key may not verify this keyspace. | 401 |
| `DISABLED` | The key was disabled. | 401 |
| `EXPIRED` | The key's expiry passed. | 401 |
| `FORBIDDEN` | Client IP not on the keyspace allow list, or the workspace is disabled. | 403 |
| `INSUFFICIENT_PERMISSIONS` | The `permissions` query was not satisfied. | 403 |
| `RATE_LIMITED` | A <Tooltip tip="Here: limits enforced by keys.verifyKey on a key or identity, or by the standalone ratelimit API. Not a Compute gateway policy.">rate limit</Tooltip> on the key or its identity was exceeded. | 429 |
| `USAGE_EXCEEDED` | The key has no credits left. | 402 or 429 |

Remaining credits are in `data.credits`, and each checked rate limit is in `data.ratelimits` with `remaining` and `reset`. The call only fails with an HTTP error (which the SDKs throw) when the call itself is wrong, such as a bad root key or a malformed body. See [Verifying keys](/api-management/keys/verifying-keys) for every field.

Then create a keyspace, which holds your keys. Use **Keyspaces (APIs)** in the dashboard, or `apis.createApi`:

```bash create a keyspace
curl -X POST https://api.unkey.com/v2/apis.createApi \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-api" }'
```

Keep the `data.apiId` from the response. You need it to create keys. See [Root keys](/platform/root-keys/overview) for more on root keys.

Create the client with `Unkey(root_key=...)`. It works as a context manager, and every method has an `_async` version for `asyncio`.

<CodeGroup>
```bash curl
curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "apiId": "api_...", "prefix": "sk_live", "externalId": "user_123", "meta": { "plan": "free" } }'
```
```python Python
import os

from unkey.py import Unkey

with Unkey(root_key=os.environ["UNKEY_ROOT_KEY"]) as unkey:
    created = unkey.keys.create_key(
        api_id=os.environ["UNKEY_API_ID"],
        prefix="sk_live",
        external_id="user_123",
        meta={"plan": "free"},
    )
    # created.data.key is the plaintext, created.data.key_id the handle you keep
    print(created.data.key_id)
```
</CodeGroup>

Every field is described in [Creating keys](/api-management/keys/creating-keys).

```python main.py
import os

import httpx
from fastapi import Depends, FastAPI, HTTPException, Request
from unkey.py import Unkey, errors

app = FastAPI()
unkey = Unkey(root_key=os.environ["UNKEY_ROOT_KEY"])

STATUS = {
    "RATE_LIMITED": 429,
    "USAGE_EXCEEDED": 402,
    "FORBIDDEN": 403,
    "INSUFFICIENT_PERMISSIONS": 403,
}


def require_key(request: Request):
    auth = request.headers.get("authorization", "")
    if not auth.startswith("Bearer "):
        raise HTTPException(status_code=401, detail="missing API key")
    key = auth[len("Bearer "):]

    try:
        res = unkey.keys.verify_key(
            key=key,
            tags=[f"endpoint={request.url.path}", f"method={request.method}"],
        )
    except (errors.UnkeyError, httpx.HTTPError) as e:
        # The call failed (bad root key, throttle, outage), not the user's key.
        raise HTTPException(status_code=503, detail="authentication unavailable") from e

    if not res.data.valid:
        code = res.data.code
        raise HTTPException(status_code=STATUS.get(code, 401), detail=code)
    return res.data


@app.get("/items")
def list_items(verification=Depends(require_key)):
    owner = verification.identity.external_id if verification.identity else None
    return {"items": [], "owner": owner}
```

For an async app, create the client with `async with Unkey(...)` and call `await unkey.keys.verify_key_async(key=key)`.

```bash
uvicorn main:app --port 3000
curl http://localhost:3000/items -H "Authorization: Bearer sk_live_..."
```

| `data.code` | Meaning | Return |
| --- | --- | --- |
| `VALID` | Every check passed. | continue |
| `NOT_FOUND` | No such key, or your root key may not verify this keyspace. | 401 |
| `DISABLED` | The key was disabled. | 401 |
| `EXPIRED` | The key's expiry passed. | 401 |
| `FORBIDDEN` | Client IP not on the keyspace allow list, or the workspace is disabled. | 403 |
| `INSUFFICIENT_PERMISSIONS` | The `permissions` query was not satisfied. | 403 |
| `RATE_LIMITED` | A <Tooltip tip="Here: limits enforced by keys.verifyKey on a key or identity, or by the standalone ratelimit API. Not a Compute gateway policy.">rate limit</Tooltip> on the key or its identity was exceeded. | 429 |
| `USAGE_EXCEEDED` | The key has no credits left. | 402 or 429 |

Remaining credits are in `data.credits`, and each checked rate limit is in `data.ratelimits` with `remaining` and `reset`. The call only fails with an HTTP error (which the SDKs throw) when the call itself is wrong, such as a bad root key or a malformed body. See [Verifying keys](/api-management/keys/verifying-keys) for every field.

<CodeGroup>
```bash cURL
curl -X POST https://api.unkey.com/v2/identities.createIdentity \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user_123",
    "ratelimits": [
      { "name": "requests", "limit": 100, "duration": 60000, "autoApply": true }
    ]
  }'
```
```typescript TypeScript
const { data } = await unkey.identities.createIdentity({
  externalId: "user_123",
  ratelimits: [
    { name: "requests", limit: 100, duration: 60_000, autoApply: true },
  ],
});
console.log(data.identityId);
```
</CodeGroup>

If the identity already exists, for example because a key was created with this `externalId` earlier, the call returns HTTP 409 `err:unkey:data:identity_already_exists`. Use `identities.updateIdentity` with the same `ratelimits` array instead.

<CodeGroup>
```bash cURL
curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "apiId": "api_...", "externalId": "user_123", "name": "Production" }'
```
```typescript TypeScript
await unkey.keys.createKey({ apiId: "api_...", externalId: "user_123", name: "Production" });
await unkey.keys.createKey({ apiId: "api_...", externalId: "user_123", name: "Staging" });
```
</CodeGroup>

<CodeGroup>
```bash cURL
curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "key": "sk_..." }'
```
```typescript TypeScript
const { data } = await unkey.keys.verifyKey({ key: incomingKey });

if (!data.valid && data.code === "RATE_LIMITED") {
  // the user exceeded 100 requests per minute across all their keys
}
console.log(data.identity?.externalId); // "user_123"
```
</CodeGroup>

`data.ratelimits` shows the limits that were checked, with `remaining` and `reset`.

curl -X POST https://api.unkey.com/v2/identities.updateIdentity \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identity": "user_123",
    "ratelimits": [
      { "name": "requests", "limit": 500, "duration": 3600000, "autoApply": true },
      { "name": "tokens", "limit": 20000, "duration": 86400000, "autoApply": false }
    ]
  }'

curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "key": "sk_...", "ratelimits": [ { "name": "tokens", "cost": 150 } ] }'

curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "api_...",
    "prefix": "sk_live",
    "name": "Acme production",
    "externalId": "org_acme",
    "meta": { "plan": "pro" },
    "expires": 1767225600000,
    "credits": {
      "remaining": 10000,
      "refill": { "interval": "monthly", "amount": 10000, "refillDay": 1 }
    },
    "ratelimits": [
      { "name": "requests", "limit": 100, "duration": 60000, "autoApply": true }
    ],
    "permissions": ["documents.read", "documents.write"]
  }'

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

curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "key": "sk_live_...", "credits": { "cost": 10 } }'

{
  "meta": { "requestId": "req_..." },
  "data": { "valid": true, "code": "VALID", "keyId": "key_...", "credits": 990 }
}

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

curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "api_...",
    "credits": {
      "remaining": 10000,
      "refill": { "interval": "monthly", "amount": 10000, "refillDay": 1 }
    }
  }'

curl -X POST https://api.unkey.com/v2/keys.updateCredits \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "keyId": "key_...", "operation": "increment", "value": 5000 }'

curl -X POST https://api.unkey.com/v2/keys.updateKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "keyId": "key_...", "enabled": false }'

{
  "meta": { "requestId": "req_..." },
  "data": { "valid": false, "code": "DISABLED", "keyId": "key_...", "enabled": false }
}

curl -X POST https://api.unkey.com/v2/keys.deleteKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "keyId": "key_..." }'

let cursor: string | undefined;
do {
  const { data, pagination } = await unkey.apis.listKeys({
    apiId: "api_...",
    externalId: "user_123",
    cursor,
  });
  for (const key of data) {
    await unkey.keys.deleteKey({ keyId: key.keyId });
  }
  cursor = pagination.hasMore ? pagination.cursor : undefined;
} while (cursor);

# expire 24 hours from now
EXPIRES=$(( $(date +%s) * 1000 + 86400000 ))

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

{
  "meta": { "requestId": "req_..." },
  "data": {
    "valid": false,
    "code": "EXPIRED",
    "keyId": "key_...",
    "enabled": true,
    "expires": 1704067200000
  }
}

# extend by 7 days from now
EXPIRES=$(( $(date +%s) * 1000 + 604800000 ))

curl -X POST https://api.unkey.com/v2/keys.updateKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"keyId\": \"key_...\", \"expires\": $EXPIRES }"

# make the key permanent
curl -X POST https://api.unkey.com/v2/keys.updateKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "keyId": "key_...", "expires": null }'

curl -X POST https://api.unkey.com/v2/keys.getKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "keyId": "key_..." }'

curl -X POST https://api.unkey.com/v2/keys.whoami \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "key": "sk_live_..." }'

{
  "meta": { "requestId": "req_..." },
  "data": {
    "keyId": "key_...",
    "start": "sk_live_abc1",
    "enabled": true,
    "name": "Acme production",
    "createdAt": 1704067200000,
    "lastUsedAt": 1704153600000,
    "expires": 1767225600000,
    "meta": { "plan": "pro" },
    "credits": {
      "remaining": 9420,
      "refill": { "interval": "monthly", "amount": 10000, "refillDay": 1 }
    },
    "ratelimits": [
      { "id": "rl_...", "name": "requests", "limit": 100, "duration": 60000, "autoApply": true }
    ],
    "permissions": ["documents.read", "documents.write"],
    "roles": ["editor"],
    "identity": { "id": "id_...", "externalId": "org_acme", "meta": {} }
  }
}

curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "api_...",
    "meta": { "plan": "pro", "features": ["exports", "webhooks"], "billingEmail": "[email protected]" }
  }'

curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "sk_live_...",
    "tags": ["endpoint=/documents", "method=GET", "region=eu-west-1"]
  }'

import { createHash } from "node:crypto";

function hashKey(plaintext: string): string {
  return createHash("sha256").update(plaintext).digest("base64");
}

hashKey("sk_live_abc"); // "5Q7m..." base64, not hex

curl -X POST https://api.unkey.com/v2/keys.migrateKeys \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "migrationId": "<from support>",
    "apiId": "api_...",
    "keys": [
      {
        "hash": "xfV3...base64...=",
        "name": "Acme production",
        "externalId": "org_acme",
        "meta": { "migratedFrom": "legacy" },
        "ratelimits": [
          { "name": "requests", "limit": 1000, "duration": 60000, "autoApply": true }
        ]
      }
    ]
  }'

{
  "meta": { "requestId": "req_..." },
  "data": {
    "migrated": [
      { "hash": "xfV3...base64...=", "keyId": "key_..." }
    ],
    "failed": [
      "duplicate...hash...="
    ]
  }
}

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

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

curl -X POST https://api.unkey.com/v2/keys.getKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "keyId": "key_...", "decrypt": true }'

{
  "meta": { "requestId": "req_..." },
  "data": {
    "keyId": "key_...",
    "start": "sk_live_abc1",
    "enabled": true,
    "createdAt": 1704067200000,
    "plaintext": "sk_live_..."
  }
}

curl -X POST https://api.unkey.com/v2/keys.rerollKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "keyId": "key_...", "expiration": 86400000 }'

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

curl -X POST https://api.unkey.com/v2/keys.updateKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyId": "key_...",
    "meta": { "plan": "pro" },
    "expires": null,
    "credits": {
      "remaining": 10000,
      "refill": { "interval": "monthly", "amount": 10000, "refillDay": 1 }
    },
    "ratelimits": [
      { "name": "requests", "limit": 1000, "duration": 60000, "autoApply": true }
    ]
  }'

{
  "meta": { "requestId": "req_..." },
  "data": {}
}

curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "sk_live_...",
    "permissions": "documents.read",
    "credits": { "cost": 2 },
    "ratelimits": [{ "name": "requests" }],
    "tags": ["endpoint=/documents", "method=GET"]
  }'

curl -X POST https://api.unkey.com/v2/apis.listKeys \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "apiId": "api_...", "externalId": "user_123", "limit": 50 }'

{
  "meta": { "requestId": "req_..." },
  "data": [
    {
      "keyId": "key_...",
      "start": "sk_prod_abc1",
      "enabled": true,
      "name": "Production key",
      "createdAt": 1704067200000,
      "expires": 1735689600000,
      "meta": { "plan": "premium" },
      "credits": { "remaining": 950 },
      "identity": { "id": "id_...", "externalId": "user_123" }
    }
  ],
  "pagination": { "cursor": "...", "hasMore": true }
}

let cursor: string | undefined;
do {
  const { data, pagination } = await unkey.apis.listKeys({
    apiId: "api_...",
    externalId: "user_123",
    cursor,
  });
  for (const key of data) {
    console.log(key.keyId, key.start);
  }
  cursor = pagination.hasMore ? pagination.cursor : undefined;
} while (cursor);

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

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

export async function handler(request: Request) {
  const userId = request.headers.get("x-user-id") ?? "anonymous";
  const result = await unkey.ratelimit.limit({
    namespace: "api.requests",
    identifier: userId,
    limit: 100,
    duration: 60_000,
  });

  if (!result.data.success) {
    const retryAfter = Math.max(1, Math.ceil((result.data.reset - Date.now()) / 1000));
    return new Response("Too many requests", {
      status: 429,
      headers: { "Retry-After": String(retryAfter) },
    });
  }

  return new Response("ok");
}

previous window                 current window
|-------------------------------|-------------------------------|
                                       ^ now, 25% into the window

effective count = current + previous * (1 - 0.25)
allowed if effective count + cost <= limit

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

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

export async function handler(request: Request) {
  const header = request.headers.get("authorization") ?? "";
  const key = header.startsWith("Bearer ") ? header.slice("Bearer ".length) : header;
  const { data } = await unkey.keys.verifyKey({ key });

  if (!data.valid && data.code === "RATE_LIMITED") {
    const resetMs = data.ratelimits?.find((limit) => limit.exceeded)?.reset ?? Date.now();
    const retryAfter = Math.max(1, Math.ceil((resetMs - Date.now()) / 1000));
    return new Response("Too many requests", {
      status: 429,
      headers: { "Retry-After": String(retryAfter) },
    });
  }

  if (!data.valid && data.code === "USAGE_EXCEEDED") {
    return new Response("Monthly quota exceeded", { status: 429 });
  }

  return data.valid ? new Response("ok") : new Response("Unauthorized", { status: 401 });
}

curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "api_...",
    "ratelimits": [
      { "name": "requests", "limit": 100, "duration": 60000, "autoApply": true },
      { "name": "exports", "limit": 5, "duration": 3600000, "autoApply": false }
    ]
  }'