> ## 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.
# Overview
> Create and manage root keys for programmatic access to the Unkey API. Root keys authenticate CLI tools, SDKs, and server-side requests.
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 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 keyspaces | Access your API endpoints |
| **Where stored** | Your server's environment variables | Given to customers |
## Create a root key
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.
Store it in your environment variables:
```bash .env theme={"theme":"kanagawa-wave"}
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**.
## Delete a root key
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](https://app.unkey.com/audit) for any unauthorized activity.
5. If you suspect API keys were created or modified, consider [rerolling](/platform/apis/features/rerolling-key) them.
Enable [GitHub secret scanning](/security/github-scanning) to get automatic alerts if your root key is accidentally committed.