Managing key roles and permissions

Change the roles and permissions on a key at any time. Set them when you create the key, replace them with keys.updateKey, or add and remove them with six dedicated endpoints. Changes take about 10 seconds to reach verification. Verifying keys describes that timing.

Create a root key with the permissions listed on this page under Root Keys in the dashboard sidebar. CLI commands can instead use a session from unkey login with the required permissions. See Permission reference for every permission.

keys.updateKey, keys.addRoles, keys.setRoles, and keys.removeRoles require unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/<key_id>#write for the target key. Wildcard grants that cover this resource and action also work. keys.setPermissions requires unkey:v1:{workspace_id}:projects/{project_id}/keyspaces/{keyspace_id}/keys/{key_id}#write. Use the keyspace ID, not the API ID. To create missing permission slugs, also grant unkey:v1:{workspace_id}:projects/{project_id}/rbac/permissions/*#write. Setting existing permissions does not require this additional grant. See the root key permission reference. Creation needs unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/*#write for the target keyspace. Use the keyspace’s project ID. keys.removePermissions needs unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/<key_id>#write for the target key. Wildcard grants that include the target key also authorize this operation. keys.addPermissions requires write on unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/<key_id>. To create a missing permission slug, keys.addPermissions also requires write on unkey:v1:<workspace_id>:projects/<project_id>/rbac/permissions/* in the key’s project. Adding existing permissions doesn’t require this additional grant. If a required write grant is missing, keys.addPermissions returns HTTP 403 when your root key can read the key. Otherwise, it returns the same HTTP 404 error as a missing key. Without the required permission-creation grant, keys.setPermissions returns HTTP 403 err:unkey:authorization:insufficient_permissions for an unknown slug. (keys.createKey and keys.updateKey create new slugs without that grant.) Roles are never created for you. An unknown role fails with HTTP 404 err:unkey:data:role_not_found.

At creation

keys.createKey accepts roles (up to 100 names, each 1 to 128 characters) and permissions (up to 1000 slugs, each 1 to 128 characters matching ^[a-zA-Z0-9_:\-\.\*]+$).

curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "api_...",
    "roles": ["editor"],
    "permissions": ["reports.export"]
  }'

Replace everything

keys.updateKey takes the same two fields. Sending a list replaces it in full. Leaving a field out keeps it as it is.

Adjust incrementally

Each endpoint takes keyId and an array of permission slugs or role names (not IDs). The add and remove endpoints need at least one entry, so [] fails with HTTP 400. Send [] to keys.setPermissions or keys.setRoles to remove everything.

Endpoint	Effect
`keys.addPermissions`	Attaches the listed permissions; ones already attached are left alone.
`keys.removePermissions`	Detaches the listed permissions; ones not attached are ignored.
`keys.setPermissions`	Replaces the direct permissions with the list; `[]` removes all.
`keys.addRoles`	Assigns the listed roles.
`keys.removeRoles`	Unassigns the listed roles.
`keys.setRoles`	Replaces the roles with the list; `[]` removes all.

curl -X POST https://api.unkey.com/v2/keys.addPermissions \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "keyId": "key_...", "permissions": ["documents.delete"] }'

Every change writes audit events, such as authorization.connect_permission_and_key and authorization.disconnect_role_and_key, so you can see the history of a key’s access.

Direct permissions versus roles

Removing a permission from a key doesn’t help if one of its roles also grants it. To take a permission away completely, remove it from the key and from the key’s roles, or remove the role. To change what a role contains, call permissions.setRolePermissions. That changes every key with the role. See Roles and permissions.

From the dashboard

Choose Manage roles and permissions from a key’s actions menu, pick roles and permissions, and save. The Create key dialog has the same pickers in its permissions step.

Get started

Framework guides

Keyspaces

Keys

Rate limiting

Identities

Authorization

Analytics

Developer portal

Security

Cookbook

Managing key roles and permissions

At creation

Replace everything

Adjust incrementally

Direct permissions versus roles

From the dashboard