Root Keys

Manage your Unkey workspace with root keys

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 Keys	API Keys
Purpose	Manage Unkey resources	Authenticate your users
Who uses it	You (the developer)	Your customers
Permissions	Create/update/delete keys, manage APIs	Access your API endpoints
Where stored	Your server’s environment variables	Given 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 case	Permissions needed
   Verify keys only	api.*.read_key
   Create keys for users	api.*.create_key, api.*.read_key
   Full key management	api.*.create_key, api.*.read_key, api.*.update_key, api.*.delete_key
   Rate limit overrides	ratelimit.*.set_override

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_...
   

Best practices

Use minimal permissions

Only grant the permissions each root key actually needs. A key that only verifies API keys doesn’t need delete_key permission.

Use separate keys for different services

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

Rotate keys periodically

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.

Never log root keys

Ensure your logging doesn’t capture root keys in request bodies or 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 rerolling them

Enable GitHub secret scanning to get automatic alerts if your root key is accidentally committed.

Next steps

GitHub Secret Scanning

Get alerts for leaked keys

Audit Logs

Monitor root key usage