> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> How roles work in Clinia IAM, including built-in roles and guidance on assigning and managing role-based access.

In the Clinia platform, roles are a key part of our Identity and Access Management (IAM) system. They define what users or services are allowed to do, ensuring that only authorized entities can access specific resources or perform certain actions. Rather than assigning individual permissions to each user or API client, we group them into roles. This makes managing access easier, safer, and more scalable.

By default, our IAM system includes predefined roles like: `admin` and `reader`.

* The `admin` role has full access to all resources and settings across the platform.
* The `reader` role is read-only, intended for users who need visibility but no modification rights.

While these system-defined roles are built-in and cannot be deleted, you're free to create as many roles as needed to match your organization's access control requirements.

## How to use them

Roles in our IAM system act as a bridge between accounts (users or service accounts) and the permissions they have in the application. Each account is assigned exactly one role at a time, which defines what they are allowed to do. For instance, if a user is given a role called `manager`, they might be able to modify records or manage users but won’t have access to the platform’s configurations or destructive actions.

<img src="https://mintcdn.com/clinia-c7642730/sOyJmKwczhIRBOEK/images/iam-roles-diagram.png?fit=max&auto=format&n=sOyJmKwczhIRBOEK&q=85&s=50ccae45260f7c6ca33fcb15204ba1ae" alt="Role relationships" width="2624" height="1184" data-path="images/iam-roles-diagram.png" />

Because roles are shared across identities, any changes to a role’s permissions will impact all users and service accounts assigned to it. For example, if the `viewer` role originally allowed read-only access to records, but is later updated to include access to users, every identity with that role immediately gains that new permission. This makes it easy to scale access management, but also requires careful review before modifying role definitions.

To maintain consistency and prevent accidental access issues, the system prevents deletion of any role that is currently in use by at least one user or service account. Before a role can be deleted, it must first be unassigned from all identities. This ensures there are no dangling references or unexpected permission losses.
