Skip to main content
In RBAC, roles represent a collection of permissions. Each role defines a set of actions or operations that a user with that role can perform. Permissions can be associated with various resources within your application, such as endpoints, data objects, or functionality. Common roles may include:
  • Administrator: Has full access to all resources and functionality.
  • Editor: Can create, read, update, and delete specific resources.
  • Viewer: Can only view resources but cannot modify them.

​
Roles

Creating, updating and deleting roles is available in the dashboard.

​
Create

  1. Go to /app/authorization/roles
  2. Click Create New Role
  3. Enter a unique name for your role and optionally a human readable description.
  4. Click Create
After the role is created, you are forwarded and can update/delete the role or connect existing permissions.

​
Update

  1. Go to /app/authorization/roles
  2. Click on the role you want to update
  3. Click Update Role
  4. Make changes to the name, description or both
  5. Click Save

​
Delete

  1. Go to /app/authorization/roles
  2. Click on the role you want to delete
  3. Click Delete Role
  4. Enter the name of the role to confirm
  5. Click Delete Role

​
Permissions

Creating, updating and deleting permissions is available in the dashboard.

​
Create

  1. Go to /app/authorization/permissions
  2. Click Create New Permission
  3. Enter a unique name for your permissoin and optionally a human readable description.
  4. Click Create New Permission

​
Update

  1. Go to /app/authorization/permissions
  2. Click on the permission you want to update
  3. Click Update Role
  4. Make changes to the name, description or both
  5. Click Save

​
Delete

  1. Go to /app/authorization/permisions
  2. Click on the permission you want to delete
  3. Click Delete
  4. Enter the name of the permission to confirm
  5. Click Delete

​
Connecting roles and permissions

After you have created at least 1 role and 1 permission, you can start associating them with each other. Go to /app/authorization/roles and click on the role to go to the permissions screen. Now you can click the checkboxes to connect the role and permission. A checked box means the role will grant the permission to keys.
Read-only roles

​
Connecting roles to keys

  1. In the sidebar, click on one of your APIs
  2. In the breakcrumb navigation on the top click Reqests and then keys
    Breadcrumb Navigation
  3. Select one of your existing keys by clicking on it
  4. Scroll down to the Roles section if not visible
You should now be on /app/keys/key_auth_???/key_???
Unconnected roles and permissions
You can connect a role to your key by clicking on the checkbox. Let’s give this key the dns.manager and read-only roles. A toast message should come up in the lower corner when the action has been completed.
Unconnected roles and permissions
As you can see, now the key now contains 2 roles and 5 permissions shown just above the Roles section:

​
Creating keys

When a user of your app creates a new key, you can attach zero, one or multiple previously created roles to the key. 
curl -XPOST \
  --url https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer ${ROOT_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "${API_ID}",
    "roles": [
      "role1", "role2", "role3"
    ]
  }'
See here for details.
⌘I