​
Roles

A role is a group of users within a tenant. Roles can be granted permissions on datasets, which apply to their members. This enables fine-grained access control within organizations and makes it easier to manage permissions for different teams.
Role-based permissions — When a role is granted a permission on a dataset, all users assigned to that role inherit that permission.

​
Role Concept

Roles are created by tenant owners and are scoped to that specific tenant. The role belongs to exactly one tenant as soon as it’s created. Because of that foreign-key link, a role can’t be moved or shared with another tenant; you would need to create a new role under the other tenant instead. Users can be assigned to multiple roles within their tenant, and roles can contain multiple users. This many-to-many relationship allows flexible permission management across teams.

​
Role-Based Permissions

When a role is granted a permission on a dataset, all users assigned to that role inherit that permission. Users receive the union of their direct permissions, tenant-level permissions, and role-level permissions. Roles allow you to create permission groups like “editors” or “viewers” within a tenant, making it easier to manage access for different teams without granting permissions to individual users.

​
Role Management

Tenant owners can:
  • Create roles within their tenant
  • Assign users to roles
  • Remove users from roles
  • Grant permissions to roles
  • Delete roles (when no longer needed)

​
Common Role Patterns

Roles are typically organized around job functions or responsibilities:
  • Editors — Can modify content and run cognify operations
  • Viewers — Can only read and search data
  • Administrators — Can manage permissions and users
  • Project Managers — Can access specific project datasets
  • Reviewers — Can read and provide feedback on content

​
Permission Inheritance Hierarchy

Users receive permissions through a three-level hierarchy:
  1. Direct permissions — Explicitly granted to the user
  2. Role permissions — Inherited through role memberships
  3. Tenant permissions — Inherited through tenant membership
The system calculates effective permissions by combining all three sources, giving users the most permissive access available to them.

​
Best Practices

  • Create meaningful role names — Use descriptive names that reflect the role’s purpose
  • Keep roles focused — Each role should have a clear, specific purpose
  • Regular role reviews — Periodically review and update role assignments
  • Document role purposes — Keep clear documentation of what each role is for
  • Principle of least privilege — Grant only the minimum permissions necessary

​
Role vs Tenant Permissions

  • Tenant permissions — Broad, organization-wide access
  • Role permissions — Specific, team-based access within the tenant
  • Direct permissions — Individual, user-specific access
This three-tier system allows for flexible and scalable permission management.

ACL

Learn how permissions are stored and checked

Snippets

See practical snippets of role-based permissions