Start with the key’s job
Describe what the service or agent needs to accomplish before choosing permissions. “Investigate a failed deployment” might mean reading its status and runtime logs. It doesn’t necessarily mean restarting it, deploying a fix, or reading environment variables. Break the job into the capabilities it needs. For example:- Deploy an app and check the result: create deployments and read their status
- Investigate a runtime problem: read deployment status and runtime logs
- Authenticate requests to your API: verify customer API keys
Choose which resources it can access
A resource is something you manage in Unkey, such as an app, deployment, or API key. The resource scope of a permission determines which of those resources the key can access. For deployments, the scope follows the structure of your workspace:- A project groups apps in your workspace.
- An app is a service you deploy.
- An environment separates an app’s settings and deployments, for example production from preview.
- A deployment is one built version of an app in one environment.
Choose what it can do with those resources
An action determines what the key can do within its scope. Most resources supportread to inspect them, write to create or update them, and delete to remove them. Some have task-specific actions, such as verify for checking customer API keys.
Choose each action separately. A deployment job needs write to create a deployment and read to check its status. A debugging agent that only inspects deployments and logs needs read, not write. Having one action doesn’t include the others.
Read-only access still needs a limited scope. Logs can contain sensitive application data, so an agent that can’t change anything may still be able to see more than its task requires.
Check all permissions on the key before using it. Permissions add access together: a permission for one environment doesn’t restrict another permission that covers every environment. To reduce access, remove or replace the broader permission. There are no deny permissions that cancel other permissions.
Read a permission
Once you’ve chosen the resources and actions, you can express each permission as a string. Unkey uses a resource name called a URN to identify the resource, followed by# and the action:
ws_xxx identifies the workspace. The path identifies the , app, environment, and deployment. #read permits reading that deployment’s details. It doesn’t permit changes or access to its logs.
IDs ending in _xxx are placeholders. Replace each one with the full ID Unkey assigned to that resource. For example, replace app_xxx with the app’s ID, not its name or slug. This applies even if an API request accepts a name or slug for the same resource.
The dashboard builds these strings from your selections. You only need to write them yourself when using the API. See Configure root keys for both methods, or continue below for scope rules and examples. The permission reference lists the supported resources, actions, and operation requirements.
Use wildcards deliberately
Use* in place of one resource ID when the task needs every resource at that position. This permission reads every deployment in one environment:
env_xxx. It doesn’t cover another environment or deployment logs. To read logs too, add:
projects/proj_xxx/apps/*/environments/env_xxx is invalid, because every ID after a wildcard must also be a wildcard. To select an environment, specify its app and project IDs too. See Build a permission string for the full rules.
Creation needs a wildcard at the resource being created because its ID doesn’t exist yet. A permission on deployments/d_xxx can’t create the next deployment. A permission on deployments/* can create deployments.
Examples
These examples turn common deployment and API Management tasks into scoped permissions. Each explains what the key needs to do and what remains outside its access. In the deployment examples,app_xxx stands for the billing app’s ID and env_xxx stands for its staging environment’s ID.
Deploy one app from CI
A CI job needs to deploy the billing app to staging and check whether the deployment succeeded. Its project, app, and environment already exist, so the job doesn’t need permission to create or configure them. Scope the key to deployments in that one environment. Addwrite for deployment creation and read for status checks. Use a deployment wildcard because each run creates a deployment with a different ID:
write authorizes deployments.createDeployment. read lets the job inspect the result with deployments.getDeployment. When using deployments.listDeployments, supply the project, app, and environment filters to match the key’s scope.
This key cannot deploy to production, change environment settings, or read environment variables. It also cannot read runtime logs unless you add the separate logs permission.
Deployment write isn’t a create-only permission. It also authorizes starting, stopping, and canceling deployments in this environment, and approving deployments from fork pull requests, subject to those operations’ restrictions. Explicit promotion and rollback require write on the environment itself. Don’t add that permission unless the job needs those operations. See deployment operation requirements.
These permissions cover the deployment API calls above. If a tool also lists projects or apps, it needs read access for those calls. Prefer supplying known IDs over adding discovery permissions the job doesn’t need.
Investigate deployments without changing them
A debugging agent needs to investigate runtime problems in the billing app’s staging environment. It needs to see deployment status and application logs, but it doesn’t need to deploy a fix or change settings. Keep the scope to that environment and assignread on two resource types: deployments and runtime logs. The logs permission is separate because reading a deployment doesn’t include reading its logs:
analytics.getRuntimeLogs. It cannot create, start, stop, promote, or roll back deployments. It cannot read environment variables or another environment’s logs.
If the investigation concerns only one deployment, replace the deployment * in both permissions with that deployment’s ID. The agent can then fetch that deployment by ID and read its logs, but it cannot list every deployment in the environment.
Read-only doesn’t mean the data is public. Logs can contain sensitive application data. Give the agent only the environment or deployment it needs, even when all its actions are read.
Verify customer API keys
A backend needs to authenticate incoming requests by checking its customers’ API keys. Those keys belong to one keyspace. The backend doesn’t need to issue keys or change their settings. Scope the root key to keys in that keyspace and chooseverify. Use a wildcard so the backend can check every customer’s key, including keys created later:
ks_xxx stands for the ID of the keyspace that holds your customers’ keys. This permission authorizes keys.verifyKey for keys in that keyspace, including keys created later. The keyspace ID in the URN is not the apiId used by some API requests.
The backend cannot list, update, delete, or decrypt keys. Verification returns its own result data and can consume credits or rate limits. verify isn’t a general-purpose read permission.
Root key permissions differ from the permissions on your customers’ API keys. Customer permissions, such as documents.read, describe access to your API and are checked during verification. They don’t grant access to Unkey resources. See Authorization.
Issue and update customer keys
A provisioning service needs to issue keys when customers sign up and update their settings when their plans change. Unlike the backend that verifies requests, this service needs to change keys. Give itwrite on keys in the customer keyspace. It doesn’t need access to other keyspaces, permission to delete keys, or permission to retrieve stored plaintext:
read on the same path only if the service needs to look up existing keys with keys.getKey. Listing keys with apis.listKeys needs both key and keyspace read access:
delete, the service can’t delete a key. It can still disable keys or change their expiry through write, so withholding delete doesn’t make a write-capable key harmless.
Give an agent a short-lived key
A trusted automation service can create a separate root key for a debugging agent. Keep key creation in that service rather than giving its credential to the agent. To create a key that reads staging deployment status and logs, the automation service needs:rootKeys/*#write from the agent’s key so it cannot create more root keys.
The service can narrow its deployment wildcard to one deployment, but it can’t grant access it doesn’t have, such as production. See the delegation and expiry rules.
rootKeys/*#write also authorizes updates to existing root keys, subject to the API’s permission and expiry checks. Treat the automation service’s key as a management credential, not a credential for ordinary workload tasks.
See Create a key through the API for the request.