API authentication

Every call to https://api.unkey.com needs a root key as a bearer token. The only exception is the customer portal’s end-user endpoints, which take a portal session instead.

Send a root key

Put the key in the Authorization header after Bearer :

curl -X POST https://api.unkey.com/v2/apis.listKeys \
  -H "Authorization: Bearer unkey_1234abcd..." \
  -H "Content-Type: application/json" \
  -d '{"apiId": "api_1234abcd"}'

A root key belongs to one workspace, and every request stays inside it. You don’t pass a workspace ID, and a key can’t reach another workspace. See Root keys to create one.

Errors a bad key returns

Status	Code	What it means
400	`err:unkey:authentication:missing`	There’s no `Authorization` header.
400	`err:unkey:authentication:malformed`	The header is missing the `Bearer` prefix, or has nothing after it.
401	`err:unkey:authentication:key_not_found`	The key doesn’t exist or was deleted.
403	`err:unkey:authorization:key_disabled`	The key is disabled.
403	`err:unkey:authorization:workspace_disabled`	The key’s workspace is disabled.
403	`err:unkey:authorization:forbidden`	The key has expired, for example because a rotation’s grace period ended.
403	`err:unkey:authorization:insufficient_permissions`	The key doesn’t have the permission the endpoint needs. The `detail` names it. Some endpoints return `404` instead, the same as if the resource didn’t exist. See Root key permissions.

All of these use the standard error envelope, so one error handler covers them.

Keep root keys safe

Treat a root key like a database password:

Create one per service with only the permissions that service needs. A leaked key then does less damage and is easy to replace.
Never put a root key in client-side code, a mobile app, or a public repository.
If one leaks, rotate or delete it under Settings > Root Keys. See Root keys.

Root keys are for managing Unkey. They aren’t the API keys you issue to your own users, which you check with keys.verifyKey. See Verifying keys.

Get started

Workspace

Billing

Root keys

API

CLI

AI coding

Security

Errors

Send a root key

Errors a bad key returns

Keep root keys safe

​Send a root key

​Errors a bad key returns

​Keep root keys safe

Send a root key

Errors a bad key returns

Keep root keys safe