Skip to main content

Roles

Create and manage roles to organize user permissions within your application.

Overview​

Roles provide a way to group permissions and assign them to users. Create app-level roles to control what users can do within your application, separate from site-level roles.

Concepts​

Role​

A named collection of permissions that can be assigned to users. Roles simplify access management by allowing you to assign permissions once to a role, then assign users to that role.

App Role​

A role scoped to a specific application. App roles are used in policy conditions to determine access to app resources.

Site Role​

A role scoped to the entire site. Site roles are managed in Site Settings and provide broader permissions.

View Roles​

  1. Navigate to your App in the Dashboard.
  2. Click Roles in the sidebar.
  3. View all app roles with:
    • Role Name: Display name
    • Slug: Unique identifier
    • Users: Number of assigned users

Create a Role​

  1. Navigate to Roles in your app.
  2. Click Create Role.
  3. Fill in the role details:
    • Name: Descriptive role name (e.g., "Editor", "Viewer")
    • Slug: URL identifier (auto-generated)
    • Description: Purpose of the role
  4. Click Create.
tip

Use descriptive names that indicate what the role allows users to do. This makes it easier to manage permissions as your app grows.

View Role Details​

  1. Click on a role in the list.
  2. View the role detail panel:
    • Role Information: Name, slug, description
    • Assigned Users: Users with this role
    • Created/Updated: Timestamps

Assign Users to a Role​

  1. Navigate to Roles in your app.
  2. Click on the role.
  3. Click Add User or Assign User.
  4. Search for and select users.
  5. Click Assign.

Bulk Assignment​

  1. Select multiple users in the user list.
  2. Click Assign to Role.
  3. Select the role.
  4. Click Assign.

Remove Users from a Role​

  1. Navigate to the role detail view.
  2. Find the user in the assigned users list.
  3. Click Remove on the user row.
  4. Confirm removal.

Edit a Role​

  1. Navigate to Roles in your app.
  2. Click the Edit icon on the role.
  3. Update role details.
  4. Click Save.
note

Changing a role's slug may affect policy conditions that reference it.

Delete a Role​

  1. Navigate to Roles in your app.
  2. Click the Delete (trash) icon on the role.
  3. Confirm deletion.
warning

Deleting a role removes all user assignments. Users will lose permissions associated with this role.

Using Roles in Policies​

Reference roles in your policy conditions:

resourcePolicy:
  resource: document
  version: default
  rules:
    - actions:
        - read
        - write
      effect: EFFECT_ALLOW
      roles:
        - editor  # Your app role
    - actions:
        - read
      effect: EFFECT_ALLOW
      roles:
        - viewer  # Another app role

Org Chart View​

Visualize role hierarchy:

  1. Navigate to Roles in your app.
  2. Click Org Chart view.
  3. See roles and their relationships.
  4. Expand nodes to see assigned users.

Configuration​

Role Fields​

FieldDescriptionRequired
NameDisplay nameYes
SlugUnique identifierAuto-generated
DescriptionPurpose of roleNo

Best Practices​

  1. Create specific roles: Better to have many focused roles than few broad ones
  2. Use clear naming: "document_editor" is clearer than "user_level_2"
  3. Document role purposes: Use the description field to explain what each role does
  4. Review regularly: Periodically audit role assignments
  5. Principle of least privilege: Only grant the permissions users need

Limits​

ResourceLimit
Roles per app50
Users per roleUnlimited
Roles per userUnlimited
info

Need higher limits? Contact support to discuss your requirements.

Troubleshooting​

User doesn't have expected access​

Problem: A user with a role isn't getting the expected permissions.

Solution:

  1. Verify the user is actually assigned to the role.
  2. Check the policy conditions reference the correct role slug.
  3. Test the policy using the Test tab in the policy editor.

Cannot delete role with users​

Problem: Role deletion fails because users are assigned.

Solution:

  1. Remove all users from the role first.
  2. Or use force delete if available.

Role slug conflicts​

Problem: Cannot create a role because the slug already exists.

Solution:

  1. Use a different name for the role.
  2. Or modify the auto-generated slug.

Last Updated: January 2025