Skip to main content
Root keys authenticate your requests to the Unkey API. They’re used to create API keys, manage identities, configure rate limits, and perform other administrative operations.
Root keys have powerful permissions. Never expose them in client-side code, commit them to git, or share them publicly.

​
Root keys vs API keys

​
Create a root key

1

Go to Settings

Navigate to Settings → Root Keys in your dashboard.
2

Click 'Create New Root Key'

3

Configure permissions

Give the key a descriptive name and select only the permissions it needs.
Common permission sets:
4

Copy and store securely

Copy the key immediately — you won’t see it again. Unkey only stores a hash.
Store it in your environment variables:
.env

​
Permissions system

Root keys use fine-grained permissions to control what operations they can perform. Always follow the principle of least privilege.

​
API permissions

  • api.*.create_key - Create new API keys
  • api.*.read_key - Read and verify API keys
  • api.*.update_key - Update existing API keys
  • api.*.delete_key - Delete API keys

​
Rate limiting permissions

  • ratelimit.*.set_override - Create and modify rate limit overrides
  • ratelimit.*.list_override - List rate limit overrides
  • ratelimit.*.delete_override - Remove rate limit overrides

​
Encryption permissions

  • encrypt_key - Store keys in encrypted vault for recovery
  • decrypt_key - Decrypt and retrieve keys from vault
Encryption and decryption permissions should only be granted when using the key recovery feature. These are powerful permissions that allow access to plaintext keys.

​
Best practices

Only grant the permissions each root key actually needs. A key that only verifies API keys doesn’t need delete_key permission.
Create dedicated root keys for each service or environment:
  • production-api-server — verify and create keys
  • admin-dashboard — full management access
  • billing-service — update 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.Rotation workflow:
  1. Create a new root key with the same permissions
  2. Update environment variables in your services
  3. Deploy the updated configuration
  4. Verify the new key is working
  5. Delete the old root key
  6. Check audit logs to confirm no usage of old key
Ensure your logging doesn’t capture root keys in request bodies or headers. Configure your logging framework to redact Authorization headers.

​
If a root key is leaked

Act immediately:
  1. Revoke the key — Go to Settings → Root Keys and delete the compromised key
  2. Create a new key — Generate a replacement with the same permissions
  3. Update your services — Deploy the new key to your environment
  4. Check audit logs — Review Audit Logs for any unauthorized activity
  5. Rotate affected API keys — If you suspect API keys were created or modified, consider rotating them
GitHub secret scanning automatically detects leaked Unkey root keys in public repositories. You’ll receive an email alert if your key is found. Learn more →

​
Environment-specific keys

Create separate root keys for each environment:
This isolation ensures:
  • Development mistakes don’t affect production
  • You can revoke development keys without impacting production
  • Audit logs clearly show which environment made each request

​
Next steps

Key Recovery

Learn about recovering leaked keys

Audit Logs

Monitor root key usage