Concepts/Roles & Permissions
More languages
More actions
Roles and permissions are how Care decides who can do what, and where. A permission is a single action ("Can Create Patient"), a role bundles permissions into a job-shaped set ("Doctor"), and a grant gives a person that role inside one boundary — a facility, an organization, or a single patient.
What it represents
There is no single FHIR resource for access control. Care builds it from three primitives that only mean something together:
- Permission — the smallest unit of access: one action, declared in code (for example
can_create_patient). Permissions are reference data; users never edit them. - Role — a flat, named bundle of permissions (Doctor, Nurse, Admin). A role is just a permission set — not a job title, not a person.
- Grant — a role handed to a user within a context. The same person can be a Doctor at one facility, an Admin of a district, and have no access anywhere else.
The key insight: a user has no standing powers of their own. Every ability comes from a role granted at a specific place. Move them to a new facility and their old access does not follow — it was scoped to the boundary where it was granted.
How a grant works
A grant always answers three questions — who, what role, where:
User ──granted──▶ Role ──scoped to──▶ Context (facility / organization / patient)
The same role at a different context is a separate grant. A grant can also carry an expiry, after which it is meant to lapse — handy for locum cover or temporary staff. One user can hold many grants at once; their effective access on any record is the union of every role that reaches it.
How access cascades
Two things make this manageable at scale rather than a grant-per-record chore.
First, permissions are context-aware. Each permission is scoped to a kind of resource, and Care only considers permissions whose context matches what is being acted on. This is why a permission to view a patient does not also let someone administer a facility — they live in different contexts.
| Context | Applies to |
|---|---|
GENERIC
|
Actions not tied to a specific resource |
FACILITY
|
A facility |
PATIENT
|
A patient record |
ENCOUNTER
|
A single encounter |
ORGANIZATION
|
A government or role (user-group) organization |
FACILITY_ORGANIZATION
|
A department or unit inside a facility |
QUESTIONNAIRE
|
A questionnaire |
Second, grants flow down the organization tree. Care's organizations nest — State → District → Local body → Facility — and a role granted at a node reaches everything beneath it. Grant an Administrator at the district level and they act across every facility in that district with no per-facility grant; grant a role on one facility and it reaches only that facility and its units. The same logic covers patients: a clinician's role at a facility lets them work with the patients seen there, instead of a grant per patient.
So you grant broadly at the top of the tree for oversight, and narrowly at a facility or department for day-to-day staff.
Standard roles
Every Care deployment ships with these roles. They are platform-maintained — the API will not let anyone edit or delete them — and deployments can add custom roles alongside. A role's boundaries are the kinds of context it can be granted in; note that a role name alone is not unique, since "Admin" exists both as a facility role and as a separate role-organization role, distinguished only by boundary.
| Role | Description | Boundaries it applies in |
|---|---|---|
| Doctor | Clinician at a facility | Facility, Government org |
| Nurse | Nurse at a facility | Facility, Government org |
| Staff | General staff at a facility | Facility, Government org |
| Volunteer | Volunteer at a facility | Facility, Government org |
| Pharmacist | Pharmacist at a facility | Facility |
| Administrator | Administrator at a given boundary | Facility, Government org |
| Facility Admin | Facility administrator, assigned to whoever creates the facility | Facility |
| Admin | Top-level administrator | Facility, Government org |
| Admin (role org) | Administrator of a role (user-group) organization | Role org |
| Manager (role org) | Manager of a role organization | Role org |
| Member (role org) | Member of a role organization | Role org |
Permissions
Permissions are declared in code per resource area and assigned to standard roles by default. The slice below — the organization and user permissions — shows which roles hold each out of the box; custom roles can take any subset.
| Permission | Description | System Roles |
|---|---|---|
can_create_organization
|
Create a new organization under an accessible parent (checked by the organization create flow) | Admin |
can_view_organization
|
View organizations; gates which organizations appear in list and retrieve | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse, Volunteer, Pharmacist, Admin (role org), Manager (role org), Member (role org) |
can_list_organization_users
|
List the users attached to an organization | Facility Admin, Admin, Staff, Doctor, Administrator, Nurse, Volunteer, Pharmacist, Admin (role org), Manager (role org) |
can_manage_organization
|
Update an organization (name, description, metadata) and delete it — the update, delete, and managing-organization actions all check this | Admin, Admin (role org) |
can_manage_organization_users
|
Add, remove, and assign roles to users in an organization | Admin, Administrator, Facility Admin, Admin (role org) |
can_manage_connected_role_organizations
|
Manage users in connected role organizations | Admin (role org), Manager (role org) |
can_create_user
|
Create a user in Care | Admin, Facility Admin, Administrator |
can_create_service_account
|
Create a service-account user | Admin, Facility Admin, Administrator |
can_list_user
|
List users in Care | Admin, Doctor, Nurse, Administrator, Staff, Facility Admin, Volunteer, Pharmacist |
Related
- Concept: Concepts/Patient
- Reference: References/Permission Association