Roles and Permissions

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.

​

Connecting roles to keys

1. In the sidebar, click on one of your APIs
2. Then click on Keys in the tabs
3. Select one of your existing keys by clicking on it
4. Go to the Permissions tab

You should now be on /app/keys/key_auth_???/key_???/permissions

You can connect a role to your key by clicking on the checkbox in the graph.

Let’s give this key the dns.manager and read-only roles.

As you can see, now the key is connected to the following permissions: domain.dns.create_record, domain.dns.read_record, domain.dns.update_record, domain.dns.delete_record, domain.create_domain, domain.read_domain

​

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.dev/v1/keys.createKey \
  -H "Authorization: Bearer ${ROOT_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "${API_ID}",
    "roles": [
      "role1", "role2", "role3"
    ]
  }'

See here for details.