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

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

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

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

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

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

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 September 29, 2026