Skip to main content
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 or edit it in the dashboard or API, and IP allowlists to limit where it can be used. This page explains how to store, rotate, disable, 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. Edits, rotation, disabling, and deletion can take up to 30 seconds to take effect.

What a root key looks like

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. If the calling key or CLI session expires, the new key must expire no later than it does. Use short-lived keys for temporary jobs and agents.

Create a root key

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

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

Rotate a root key

Rotating gives you a new root key with the same name, permissions, IP allowlist, and expiry, 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. The default is 24 hours. To keep the old key’s current expiry, select Do not expire original key.
  3. Check the confirmation box, 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.

Disable a root key

Disabling stops a key from authenticating without deleting it, so you can turn it back on later. Use it to pause a workload or to cut off a key while you investigate. The dashboard can’t disable a key. Set enabled to false with rootKeys.updateKey, or use unkey root-keys update with --enabled=false. The caller needs write on that root key.
Requests with a disabled key fail with err:unkey:authorization:key_disabled. The dashboard shows the key as Disabled. To turn it back on, set enabled to true. Rotating a disabled key gives you a disabled replacement.

Delete a root key

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

If a root key leaks

Rotate it with “revoke immediately” or delete it, then remove the secret from wherever it was exposed. The key keeps working until you do, and revocation can take up to 30 seconds to take effect. 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.

Permission details

Root key permissions

Choose least-privilege permissions for deployments, agents, and API Management.

Permission reference

Resource paths, supported actions, and operation requirements.
Last modified on November 12, 2026