What a root key looks like
A root key starts withunkey_, 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.- Choose Rotate root key from the row menu.
- 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.
- Check the confirmation box, click Rotate root key, then confirm the rotation.
- Copy the new key. It’s shown once, like a new key.
- Update your services before the grace period ends.
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. Setenabled to false with rootKeys.updateKey, or use unkey root-keys update with --enabled=false. The caller needs write on that root key.
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.