Skip to main content

​
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.
The Role model defines what gets stored in the SQL database. The roles table contains:
  • id: Unique identifier (UUID primary key, references principals.id)
  • name: Human-readable name (unique within tenant)
  • tenant_id: ID of the tenant this role belongs to (required)
  • create_role(role_name, owner_id): Creates a new role (tenant owner only)
  • add_user_to_role(user_id, role_id, owner_id): Assigns a user to a role (tenant owner only)
  • delete_role(role_id, owner_id): Deletes a role, removes all user-role memberships for that role, and revokes dataset permissions granted to the role principal. Exposed via DELETE /api/v1/permissions/roles/{role_id}.
  • remove_user_from_role(user_id, role_id, owner_id): Removes a user from a specific role without removing them from the tenant. Exposed via DELETE /api/v1/permissions/users/{user_id}/roles.
Use remove_user_from_tenant (see Tenants) only when you want to remove a user from the entire tenant. That operation also strips the user from all roles in the tenant and revokes their direct dataset permissions for tenant-owned datasets.
  • Roles are tenant-scoped and cannot cross tenants
  • API endpoints for role management

​
Role Management

Tenant owners can:
  • Create roles within their tenant
  • Assign users to roles
  • Remove users from roles
  • Grant permissions to roles
  • Delete roles

​
Role Visibility

Administering roles is owner-only, but reading them is scoped to membership:
  • Roles you belong to — GET /api/v1/permissions/tenants/{tenant_id}/roles returns 200 for any authenticated caller when the tenant exists (a nonexistent tenant_id still returns 404). Callers who are the tenant owner or have user-management permission (for example, an Admin role) see every role in the tenant; everyone else sees only the roles they are a member of. A caller who belongs to no role in that tenant — including a caller who passes a tenant_id for a tenant they are not part of — receives an empty list rather than an error.
  • Members of those roles — GET /api/v1/permissions/tenants/{tenant_id}/roles/{role_id}/users is visible to members of the role itself, so users can see who shares their roles. A caller who is not a member and lacks user-management permission receives 403. The role is resolved within the tenant in the path, so a role_id belonging to another tenant returns 404 instead of that tenant’s members.
  • The full tenant user directory — GET /api/v1/permissions/tenants/{tenant_id}/users still requires tenant ownership or user-management permission. Role membership alone does not grant it.
  • The datasets granted to a role — GET /api/v1/permissions/principals/{principal_id}/datasets returns the datasets a principal holds a permission on, so you can answer “which datasets does this team have?”. The optional permission_name query parameter selects which permission to list and defaults to read; the other accepted values are write, delete, and share. For a role principal_id, the endpoint is visible to members of that role, so users can list the datasets of the roles they belong to; a non-member who is not the tenant owner and lacks user-management permission receives 403. The role is resolved within the caller’s current tenant, so a role_id belonging to another tenant returns 404 rather than revealing that tenant’s datasets. The response is a JSON list of dataset objects, and it is always narrowed to the caller’s current tenant.

​
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