unkey:v1:{workspace_id}:{resource_path}#{action}. Use this page to choose a path and action. See Root key permissions for least-privilege examples and Configure root keys to assign them.
Build a permission string
Replace placeholders such as{project_id} with resource IDs, not names or slugs. A resource ID can be * to select all resources at that position, including future resources. After the first wildcard ID, every later ID must also be *. The workspace ID must always be exact.
Paths and actions are case-sensitive. Keep path segments such as rootKeys exactly as shown. IDs contain letters, digits, and underscores. Partial ID matches such as proj_* aren’t supported.
For example, to read every app in one project:
_xxx are placeholders. Replace ws_xxx and proj_xxx with the full workspace and project IDs.
The resource tables list supported path/action combinations. They don’t mean every combination has a corresponding API endpoint. Use the operation requirements below when an endpoint needs a collection permission or more than one permission.
Workspace resources
Append one of these paths tounkey:v1:{workspace_id}:, then add # and an action.
Deploy resources
All paths in this table follow the prefixunkey:v1:{workspace_id}:projects/{project_id}/.
The resources below follow the environment prefix:
# and the action. In these suffixes, {id} is the ID of the deployment, domain, variable, or policy. For example, append /deployments/*#read to read deployments in that environment.
Deployment operations
These requirements use the environment prefix above. Here,{id} is the deployment ID. Each row identifies the resource and action the operation checks.
When listing deployments with an environment-scoped key, include the
project, app, and environment request filters. A broader list request needs a broader permission. For logs, the API restricts results to the deployments covered by the key’s log permissions.
Environment write also authorizes environment settings changes. Deployment write authorizes both creation and updates within its scope. Neither action is a create-only or promote-only permission. Permissions don’t bypass operation restrictions, such as which deployments can be stopped.
Environment variable operations
Variable endpoints check the collection path/variables/*, not a single variable ID.
Read access can reveal recoverable variable values. It doesn’t reveal write-only values. There is no separate
decrypt permission for environment variables. Don’t grant variable read access to an agent that only needs deployment logs.
API management resources
All paths in this table followunkey:v1:{workspace_id}:projects/{project_id}/.
Use the keyspace ID in permission paths, not the
apiId accepted by some key-management requests. Roles and permission definitions in this table are resources used to authorize your customers’ keys. They aren’t the root key permissions themselves.
Key operations
For these operations, append each suffix tounkey:v1:{workspace_id}:projects/{project_id}/keyspaces/{keyspace_id}.
When
keys.addPermissions or keys.setPermissions must create a missing permission definition, also grant write on projects/{project_id}/rbac/permissions/*. Attaching an existing definition doesn’t need that extra creation permission.
Root key operations
These suffixes followunkey:v1:{workspace_id}:. A caller that assigns permissions must already cover each assigned permission in the same workspace.
Creating or updating a key cannot assign permissions beyond the caller’s permissions. Rotation checks that the caller covers the permissions being copied to the replacement key. The management permission alone doesn’t grant permission to copy broader access.
See Configure root keys for creation, permission replacement, and expiry rules.