Skip to main content
You can create a root key and assign its permissions in the dashboard or through the API. Both methods control the same access. If you’re still deciding what your service or agent needs, start with Root key permissions. This guide creates a key for a debugging agent. The agent can read deployment status and runtime logs in the billing app’s staging environment. It cannot deploy changes or access other environments. The dashboard steps and API request below configure that same permission set.

​
Create a key in the dashboard

You need the workspace admin role to manage root keys in the dashboard.
1

Open the root key form

Open Root Keys in your workspace and click New Root Key.
2

Name the key

Enter a name such as billing-staging-debugger that describes the key’s job.
3

Start a custom policy

Under Permissions, select Start new. The policy editor opens with no actions selected.
4

Choose the environment

Set Scope to Environments, then select the billing app’s staging environment instead of all environments.
5

Select the actions

Select Read on Deployments and Runtime logs. Leave the other actions and resources unselected.
6

Review and create the key

Close the policy editor with its × button to review the summary. Check every policy on the key, then click Create key.
7

Store the secret

Use the copy button beside the key and save the secret in your secret manager. Unkey shows it only once. Click Done after saving it.
A policy groups a scope and its selected actions. Selecting the environment sets the boundary for the deployment and log permissions; it doesn’t automatically grant access to environment settings or variables. Use Add policy when the key needs another scope. Policies add access together, so a workspace-wide policy can make a narrower environment policy ineffective as a restriction. Templates are starting points, not least-privilege recommendations. For example, All read permissions includes more data than deployment status and logs, and Verify keys starts with every keyspace. Review both the resources and actions before saving. Changing Scope resets that policy’s selections. Use the API below if you need an expiry or a permission on one exact deployment rather than all deployments in the selected environment.

​
Edit permissions in the dashboard

Open the key’s row menu and select Edit root key. Change its policies, review the complete selection, then click Save changes.
Saving replaces the key’s permission set. To narrow access, remove broader policies as well as adding narrower ones. Clearing a search filter before reviewing helps you see selections that the filter hides. For rotation and deletion, see Root keys.

​
Create a key through the API

Authenticate with a root key that has unkey:v1:ws_xxx:rootKeys/*#write and covers every permission you’re assigning. If you don’t have a management key yet, create one in the dashboard first. Keep that credential in trusted automation, not in the agent that receives the new key. This request creates a debugging key that expires in one hour. IDs ending in _xxx are placeholders. Replace each one with the full resource ID, not a name or slug. Use the billing app’s ID for app_xxx and its staging environment’s ID for env_xxx. Set UNKEY_ROOT_KEY through your secret manager or environment, rather than putting the secret in the script.
The response contains data.key, the secret shown only once, and data.keyId, the ID used to manage the key. Store the secret without sending it to CI logs or application logs. Give the agent the new secret, not UNKEY_ROOT_KEY. The permissions array is required. Every entry must be a supported resource/action combination in the authenticated workspace and fit within the caller’s permissions. The API accepts an empty array, but that key grants no resource access. expires is a future Unix timestamp in milliseconds. If the caller’s root key expires sooner than one hour from now, use an earlier expiry. An expiring caller must set an expiry no later than its own. A nonexpiring caller can omit expires or use null for a key with no expiry, but use a short lifetime for temporary tasks.

​
Replace permissions through the API

Use rootKeys.updateKey with the target keyId and the complete permission list you want to keep. The caller needs write on that root key and must cover every permission in the replacement list. For example, narrow the debugging key to one deployment:
Replace key_xxx with data.keyId from creation and d_xxx with the deployment’s ID. This request removes the environment-wide deployment permissions and replaces them with permissions on that deployment. It doesn’t append to the existing list. Omitting permissions leaves the existing permissions unchanged. Sending "permissions": [] removes all permissions. An expiring root key can only update keys that expire no later than itself.

​
Verify the resulting access

Call an operation the key needs, then check a read outside its scope. For the single-deployment debugging key, deployments.getDeployment on the deployment represented by d_xxx must succeed, while a lookup of a different deployment must fail. If a request fails unexpectedly, compare its required action and resource IDs with the full permission list. Check list filters too: a request for all deployments asks for more access than a request scoped to one environment. See permission troubleshooting.
Last modified on October 2, 2026