Skip to main content

Documentation Index

Fetch the complete documentation index at: https://unkey.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

Rotation issues a new root key with the same permissions as the original and schedules the old key to expire after a grace period you choose. Use it for routine credential rotation or to replace a leaked key without downtime.
  1. Navigate to Settings > Root Keys.
  2. Click the actions menu (…) on the key row.
  3. Select Rotate root key.
  4. Choose a grace period for the old key:
    • Revoke immediately – revoke the old key as soon as the new one is created.
    • 1 minute, 15 minutes, 1 hour, 6 hours, or 24 hours – keep the old key valid for that long so deployed services keep working while you roll out the new key.
  5. Click Rotate key.
  6. Copy the new key secret from the success dialog and store it. The plaintext is shown only once.
  7. Update your application’s environment variables with the new key and deploy.
The new key inherits the original permissions and any expiration that was already set. The old key continues to verify until the grace period elapses, then it is revoked automatically. Expired keys cannot be rotated; create a new key instead.
Choose a grace period that covers your slowest deploy. If a service still uses the old key after the grace period ends, it will receive an EXPIRED response.

​
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 May 8, 2026