Roles & Permissions

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

• Reference: Role
• Reference: Permission
• Reference: Permission association
• Concept: Organization
• Concept: Facility
• Concept: Patient