[IAM]
Roles
Roles define what a user or group is allowed to do within a specific Realm and Organisation context.
They act as the central abstraction between identity (users/groups) and permissions (scopes/actions).
What is a role?
A role is a collection of permissions that represents a functional access level.
Roles are used to:
- Define access levels (e.g. admin, editor, viewer)
- Group permissions into reusable sets
- Assign capabilities to users via groups or direct assignment
- Control access across applications and APIs
A role itself does not perform actions — it defines what is allowed.
Roles in IAM structure
Roles sit between groups and permissions:
User → Group → Role → Permission
This ensures that access is structured, reusable, and scalable.
Roles and permissions
Roles are composed of one or more permissions (scopes).
For example:
- A role may include
users.read,users.write - Another role may include
invoices.read,invoices.create
Permissions define the actual allowed actions, while roles define the packaging of those permissions.
Roles and groups
Roles are typically assigned through groups:
- Groups contain one or more roles
- Users inherit roles through group membership
- This allows access control to scale across many users
In some cases, roles can also be assigned directly to users for exceptions or specific needs.
Roles and organisations
Roles are always evaluated within an organisation context.
This means:
- The same role can behave differently per organisation
- Roles can be scoped or applied per organisation
- Access decisions depend on both role and organisation
This ensures that access remains aligned with real-world business structures.
Role types
IAM supports different types of roles, including:
- Standard roles — general-purpose access roles (admin, user, viewer)
- Scoped roles — roles limited to specific organisations or applications
- System roles — roles used for platform-level or administrative access
- Custom roles — defined by customers within their own realms
Role inheritance model
Roles are not hierarchical, but they can be combined:
- Users may have multiple roles via different groups
- Permissions are aggregated across all assigned roles
- Final access is the union of all permissions granted
This allows flexible but predictable access control.
Security model
Roles enforce security by:
- Limiting access to only defined permissions
- Reducing direct permission assignment complexity
- Centralising access definitions for reuse
- Ensuring consistent enforcement across services
All role changes are immediately reflected in access decisions.
Why roles matter
Roles are a core part of IAM because they:
- Bridge users and permissions in a scalable way
- Enable structured access control across organisations
- Reduce complexity in large identity systems
- Provide a reusable model for permission management
Without roles, IAM would rely on direct permission assignments, which would not scale.