Skip to main content
Root keys authenticate your requests to the Unkey API. Each root key belongs to a single workspace and can only access resources within that workspace. Use them to create API keys, manage identities, configure rate limits, and perform other administrative operations from your server.
Root keys have powerful permissions. Never expose them in client-side code, commit them to git, or share them publicly.
Root key list

​
Root keys vs API keys

Root keysAPI keys
PurposeManage Unkey resourcesAuthenticate your users
Who uses itYou (the developer)Your customers
PermissionsCreate/update/delete keys, manage APIsAccess your API endpoints
Where storedYour server’s environment variablesGiven to customers

​
Create a root key

Create root key dialog
  1. Navigate to Settings > Root Keys.
  2. Click Create New Key.
  3. Enter a descriptive name (for example, “Vercel Production” or “CI Pipeline”).
  4. Select the permissions the key needs. Grant only what the key requires.
  5. Click Create root key.
The key secret is displayed once after creation. Copy it immediately, as you cannot retrieve it later. Unkey only stores a hash of the key.
Copy root key secret
Store it in your environment variables:
.env
UNKEY_ROOT_KEY=unkey_...

​
Edit a root key

  1. Navigate to Settings > Root Keys.
  2. Click the actions menu (…) on the key row.
  3. Select Edit root key….
  4. Update the name or permissions.
  5. Click Update root key.
Edit root key dialog

​
Delete a root key

Delete root key confirmation
  1. Navigate to Settings > Root Keys.
  2. Click the actions menu (…) on the key row.
  3. Select Delete root key.
  4. Check the confirmation box and click Delete permanently.
Deleting a root key is immediate and permanent. Any application using the key loses access.

​
Rotate a root key

To rotate a root key without downtime:
  1. Create a new root key with the same permissions as the existing one.
  2. Update your application’s environment variables with the new key.
  3. Deploy the change.
  4. Verify the new key is working by checking your application logs or the Unkey audit log.
  5. Delete the old root key.
Both keys are valid simultaneously, so your application continues to work throughout the process.

​
Best practices

Only grant the permissions each root key actually needs. A key that only verifies API keys does not need delete_key permission.
Create dedicated root keys for each service or environment. For example, production-api-server for verifying and creating keys, admin-dashboard for full management access, and billing-service for updating key credits only.
Even without a breach, rotate root keys every few months as a security practice. Create a new key, update your services, then delete the old one.
Ensure your logging does not capture root keys in request bodies or headers.

​
If a root key is leaked

Act immediately:
  1. Go to Settings > Root Keys and delete the compromised key.
  2. Create a replacement key with the same permissions.
  3. Deploy the new key to your environment.
  4. Review audit logs for any unauthorized activity.
  5. If you suspect API keys were created or modified, consider rerolling them.
Enable GitHub secret scanning to get automatic alerts if your root key is accidentally committed.
Last modified on March 30, 2026