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

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

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:
Use casePermissions needed
Verify keys onlyapi.*.read_key
Create keys for usersapi.*.create_key, api.*.read_key
Full key managementapi.*.create_key, api.*.read_key, api.*.update_key, api.*.delete_key
Rate limit overridesratelimit.*.set_override
Key encryptionencrypt_key
Key decryptiondecrypt_key
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
UNKEY_ROOT_KEY=unkey_...

​
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.
// Good - redact authorization header
logger.info('API request', {
  url: req.url,
  headers: {
    ...req.headers,
    authorization: '[REDACTED]'
  }
});

​
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: 
# Development
UNKEY_ROOT_KEY=unkey_dev_...

# Staging
UNKEY_ROOT_KEY=unkey_staging_...

# Production
UNKEY_ROOT_KEY=unkey_prod_...
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

Build docs developers (and LLMs) love

Get started for freeTalk to us