Admin: Automated edit (via update-page on MediaWiki MCP Server)

2026-07-06T04:02:37Z

Automated edit (via update-page on MediaWiki MCP Server)

← Older revision		Revision as of 09:32, 6 July 2026
Line 166:		Line 166:
	\| Admin, Doctor, Nurse, Administrator, Staff, Facility Admin, Volunteer, Pharmacist		\| Admin, Doctor, Nurse, Administrator, Staff, Facility Admin, Volunteer, Pharmacist
	\|}		\|}

			{{Navbox access governance}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T22:42:57Z

OHC identity seed

New page

{{Doc header
|type=concept
|domain=access-governance
|title=Roles & Permissions
|order=1
|introduced=3.0
|concept=Concepts/Patient
|reference=References/Permission Association
}}

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 <code>can_create_patient</code>). 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'':

<syntaxhighlight lang="text">User ──granted──▶ Role ──scoped to──▶ Context (facility / organization / patient)</syntaxhighlight>
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.

{| class="wikitable"
|-
! Context
! Applies to
|-
| <code>GENERIC</code>
| Actions not tied to a specific resource
|-
| <code>FACILITY</code>
| A facility
|-
| <code>PATIENT</code>
| A patient record
|-
| <code>ENCOUNTER</code>
| A single encounter
|-
| <code>ORGANIZATION</code>
| A government or role (user-group) organization
|-
| <code>FACILITY_ORGANIZATION</code>
| A department or unit inside a facility
|-
| <code>QUESTIONNAIRE</code>
| A questionnaire
|}

Second, '''grants flow down the organization tree'''. Care's [[Concepts/Organization|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.

{| class="wikitable"
|-
! 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.

{| class="wikitable"
|-
! Permission
! Description
! System Roles
|-
| <code>can_create_organization</code>
| Create a new organization under an accessible parent (checked by the organization create flow)
| Admin
|-
| <code>can_view_organization</code>
| 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)
|-
| <code>can_list_organization_users</code>
| List the users attached to an organization
| Facility Admin, Admin, Staff, Doctor, Administrator, Nurse, Volunteer, Pharmacist, Admin (role org), Manager (role org)
|-
| <code>can_manage_organization</code>
| Update an organization (name, description, metadata) and delete it — the update, delete, and managing-organization actions all check this
| Admin, Admin (role org)
|-
| <code>can_manage_organization_users</code>
| Add, remove, and assign roles to users in an organization
| Admin, Administrator, Facility Admin, Admin (role org)
|-
| <code>can_manage_connected_role_organizations</code>
| Manage users in connected role organizations
| Admin (role org), Manager (role org)
|-
| <code>can_create_user</code>
| Create a user in Care
| Admin, Facility Admin, Administrator
|-
| <code>can_create_service_account</code>
| Create a service-account user
| Admin, Facility Admin, Administrator
|-
| <code>can_list_user</code>
| List users in Care
| Admin, Doctor, Nurse, Administrator, Staff, Facility Admin, Volunteer, Pharmacist
|}

{{Related}}

Concepts/Roles & Permissions - Revision history

Admin: Automated edit (via update-page on MediaWiki MCP Server)

Admin: OHC identity seed