View source for References/Permission

{{Doc header
|type=reference
|domain=access-governance
|title=Permission
|order=4
|introduced=3.0
|model=Permission
|reference=References/Base models &amp; conventions
}}

A permission is the ability to perform one action in one context — read it as &quot;Action on Resource&quot;, like &quot;Can Create Patient&quot; in the <code>PATIENT</code> context. Permissions are the atoms of Care's access control: code declares them, the sync command writes them to the database, [[References/Role|roles]] group them, and [[References/Permission Association|permission associations]] bind them to resources. You rarely touch this table directly; you reference its rows by <code>slug</code> when building roles.

The Django <code>PermissionModel</code> is only storage; two other places do the real work. The permission registry (<code>care/security/permissions/</code>) declares every permission as a Python <code>enum</code> member carrying a <code>name</code>, <code>description</code>, <code>context</code>, and the default <code>roles</code> that hold it. The Pydantic resource specs (<code>care/emr/resources/role/spec.py</code>) define the read API schema. This doc covers all three.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/security/models/permission.py <code>care/security/models/permission.py</code>]
* Spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/role/spec.py <code>care/emr/resources/role/spec.py</code>] (<code>PermissionSpec</code>)
* Computed-permission mixins: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/permissions.py <code>care/emr/resources/permissions.py</code>]
* Registry: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/security/permissions/base.py <code>care/security/permissions/base.py</code>], [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/security/permissions/constants.py <code>care/security/permissions/constants.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>PermissionModel</code>
| A single, named permission (action) that can be granted to a user in a context
|}

<code>PermissionModel</code> extends [[References/Base models &amp; conventions|<code>BaseModel</code>]], the lowest-level Care base — not <code>EMRBaseModel</code>. That means no <code>created_by</code>/<code>updated_by</code>, no <code>history</code>, no <code>meta</code> columns. The inherited fields:

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Permission|section=Models|name=external_id|type=UUIDField|notes=<code>default=uuid4</code>, <code>unique</code>, indexed. Opaque public identifier — never expose the integer <code>pk</code>}}
{{Field|model=Permission|section=Models|name=created_date|type=DateTimeField|notes=<code>auto_now_add</code>; nullable, indexed}}
{{Field|model=Permission|section=Models|name=modified_date|type=DateTimeField|notes=<code>auto_now</code>; nullable, indexed}}
{{Field|model=Permission|section=Models|name=deleted|type=BooleanField|notes=<code>default=False</code>, indexed. Soft-delete flag; the default manager hides <code>deleted=True</code> rows}}
|}

== <code>PermissionModel</code> fields ==

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=Permission|section=PermissionModel fields|name=slug|type=CharField(1024)|notes=yes}}
{{Field|model=Permission|section=PermissionModel fields|name=name|type=CharField(1024)|notes=yes}}
{{Field|model=Permission|section=PermissionModel fields|name=description|type=TextField|notes=no}}
{{Field|model=Permission|section=PermissionModel fields|name=context|type=CharField(1024)|notes=yes}}
{{Field|model=Permission|section=PermissionModel fields|name=temp_deleted|type=BooleanField|notes=no}}
|}

=== <code>context</code> values (<code>PermissionContext</code>) ===

<code>context</code> is a free-form <code>CharField</code> in the database, but the registry only writes one of these enum values ([<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/security/permissions/constants.py <code>constants.py</code>]):

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>GENERIC</code>
| Not scoped to a specific resource type
|-
| <code>FACILITY</code>
| Scoped to a facility
|-
| <code>PATIENT</code>
| Scoped to a patient
|-
| <code>QUESTIONNAIRE</code>
| Scoped to a questionnaire
|-
| <code>ORGANIZATION</code>
| Scoped to a (govt/role) organization
|-
| <code>FACILITY_ORGANIZATION</code>
| Scoped to a facility organization
|-
| <code>ENCOUNTER</code>
| Scoped to an encounter
|}

The value is load-bearing: when resolving access for a serialized resource, the mixins below filter on <code>permission__context__in=[...]</code>, so only permissions in the matching context count.

== Related models ==

=== Registry declaration — <code>Permission</code> dataclass ===

Permissions are authored in code, not the database. Each one is a member of a <code>*Permissions</code> <code>enum</code>, one per resource area (<code>PatientPermissions</code>, <code>EncounterPermissions</code>, and so on). The member name becomes the <code>slug</code>; the member value is a <code>Permission</code> dataclass ([<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/security/permissions/constants.py <code>constants.py</code>]):

{| class="wikitable"
|-
! Field
! Type
! Maps to <code>PermissionModel</code>
! Notes
{{Field|model=Permission|section=Registry declaration — Permission dataclass|name=name|type=str|notes=<code>name</code>}}
{{Field|model=Permission|section=Registry declaration — Permission dataclass|name=description|type=str|notes=<code>description</code>}}
{{Field|model=Permission|section=Registry declaration — Permission dataclass|name=context|type=PermissionContext|notes=<code>context</code> (<code>.value</code>)}}
{{Field|model=Permission|section=Registry declaration — Permission dataclass|name=roles|type=list[Role]|notes=— (drives <code>RolePermission</code>)}}
|}

Example (<code>care/security/permissions/patient.py</code>):

<syntaxhighlight lang="python">can_create_patient = Permission(
    "Can Create Patient", "", PermissionContext.PATIENT,
    [STAFF_ROLE, DOCTOR_ROLE, NURSE_ROLE, ADMINISTRATOR, ADMIN_ROLE, FACILITY_ADMIN_ROLE],
)</syntaxhighlight>
<code>PermissionController</code> ([<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/security/permissions/base.py <code>base.py</code>]) aggregates every handler enum:

* <code>get_permissions() → dict[slug, Permission]</code> — the full declared registry (cached).
* <code>get_enum() → Enum</code> — a dynamically built <code>str</code> enum of all permission slugs, used by [[References/Role|<code>RoleCreateSpec</code>]] to constrain the <code>permissions</code> write field to known slugs.

=== Sync command (<code>sync_permissions_roles</code>) ===

The management command [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/security/management/commands/sync_permissions_roles.py <code>sync_permissions_roles</code>] is the only writer of this table. It is idempotent, Redis-locked, and runs in a single transaction:

# Mark every <code>PermissionModel</code> <code>temp_deleted=True</code>.
# For each declared permission, upsert by <code>slug</code> — setting <code>name</code>, <code>description</code>, <code>context</code> (from <code>Permission.context.value</code>) and clearing <code>temp_deleted</code>.
# Hard-delete any row still <code>temp_deleted=True</code> (no longer declared).
# Upsert system roles, then rebuild <code>RolePermission</code> rows from each <code>Permission.roles</code> list, using the same mark-then-prune pattern.

=== <code>RolePermission</code> ===

Permissions reach users only through roles. <code>RolePermission</code> is the join table (<code>role</code> FK, <code>permission</code> FK, <code>temp_deleted</code>) connecting a [[References/Role|<code>RoleModel</code>]] to a <code>PermissionModel</code>. A user's effective access is the union of permissions across their role bindings, filtered to active grants (<code>rolepermission__temp_deleted=False</code>).

== Resource specs (API schema) ==

The Pydantic specs build on <code>EMRResource</code> ([<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/base.py <code>base.py</code>]), whose <code>serialize</code> (DB → spec) and <code>de_serialize</code> (spec → DB) drive read and write, with <code>perform_extra_serialization</code>/<code>perform_extra_deserialization</code> hooks for side effects.

{| class="wikitable"
|-
! Spec class
! Role
! File
! Notes
|-
| <code>PermissionSpec</code>
| read · list + detail
| <code>role/spec.py</code>
| The only permission-facing spec. Served read-only by <code>PermissionViewSet</code>
|-
| <code>PermissionsMixin</code>
| read augmentation
| <code>permissions.py</code>
| Adds the requesting user's computed <code>permissions</code> list to other resources' serialized output
|}

No <code>PermissionCreateSpec</code> or <code>PermissionUpdateSpec</code> exists: permissions are reference data, never client-writable. Write specs exist for roles instead — see [[References/Role]].

=== <code>PermissionSpec</code> ===

<code>__model__ = PermissionModel</code>. A flat read schema with no extra serialization hooks; it inherits the base mapping that sets <code>id = external_id</code>:

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Permission|section=PermissionSpec|name=name|type=str|notes=From <code>PermissionModel.name</code>}}
{{Field|model=Permission|section=PermissionSpec|name=description|type=str|notes=From <code>PermissionModel.description</code>}}
{{Field|model=Permission|section=PermissionSpec|name=slug|type=SlugType|notes=<code>str</code>, <code>min_length=5</code>, <code>max_length=50</code>, must match <code>^[a-zA-Z0-9][a-zA-Z0-9_-]*[a-zA-Z0-9]$</code> (URL-safe; starts and ends alphanumeric). See [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/utils/slug_type.py <code>slug_type.py</code>]}}
{{Field|model=Permission|section=PermissionSpec|name=context|type=str|notes=One of the <code>PermissionContext</code> values above}}
{{Field|model=Permission|section=PermissionSpec|name=id|type=UUID4|notes=Added by <code>serialize</code> as <code>external_id</code> (inherited base behaviour)}}
|}

Served by [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/security/api/viewsets/permissions.py <code>PermissionViewSet</code>], an <code>EMRModelReadOnlyViewSet</code> (list + retrieve only) with <code>lookup_field=&quot;slug&quot;</code>, filterable by <code>name</code> (<code>icontains</code>). No create, update, or delete endpoint exists.

=== Computed <code>permissions</code> on other resources (<code>PermissionsMixin</code>) ===

[<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/permissions.py <code>permissions.py</code>] defines mixins that other read specs inherit, so a serialized resource carries the current user's effective permission slugs for that object. For authenticated users, <code>PermissionsMixin.perform_extra_user_serialization</code> calls <code>add_permissions(mapping, user, obj)</code> to populate a <code>permissions: list[str]</code> field:

{| class="wikitable"
|-
! Mixin
! Output fields
! Resolution
|-
| <code>PatientPermissionsMixin</code>
| <code>permissions</code>
| Roles on the patient; permission slugs where <code>context in [&quot;PATIENT&quot;, &quot;FACILITY&quot;]</code>
|-
| <code>EncounterPermissionsMixin</code>
| <code>permissions</code>
| Roles on the encounter; permission slugs where <code>context in [&quot;ENCOUNTER&quot;, &quot;PATIENT&quot;]</code>
|-
| <code>FacilityPermissionsMixin</code>
| <code>permissions</code>, <code>root_org_permissions</code>, <code>child_org_permissions</code>
| Union of root-org and sub-org role permissions; <code>child_org_permissions</code> excludes the <code>can_update_facility</code> slug
|}

The frontend reads these lists to gate UI by capability, skipping a separate authorization round-trip.

== Methods &amp; save behaviour ==

<code>PermissionModel</code> adds no custom <code>save()</code>, <code>delete()</code> override, validators, or signals — everything comes from <code>BaseModel</code>, including soft-delete (<code>delete()</code> setting <code>deleted=True</code>) and the default manager that filters out soft-deleted rows. The lifecycle runs externally through <code>sync_permissions_roles</code> (above), which stages with <code>temp_deleted</code> and hard-deletes undeclared rows.

<code>PermissionSpec</code> runs no extra serialization or deserialization: just the base <code>serialize</code> flow plus the inherited <code>id = external_id</code> mapping.

== API integration notes ==

* Permissions are platform-maintained reference data: declared in the registry, synced into this table by <code>sync_permissions_roles</code>, read-only over the API. <code>PermissionViewSet</code> exposes list + retrieve only.
* Reference a permission by <code>slug</code> — it is stable, <code>unique</code>, and the API <code>lookup_field</code>. Treat <code>external_id</code> as the opaque public ID; never expose the integer <code>pk</code>.
* You can't grant a permission directly to a user. A [[References/Role|role]] collects permissions (via <code>RolePermission</code>), and a [[References/Permission Association|permission association]] binds that role to a resource — organization, patient, encounter, and so on. Effective access is the union of active permissions across a user's role bindings.
* <code>context</code> has no DB <code>choices</code> but is always a <code>PermissionContext</code> enum string. The mixins filter resource permissions by context, so the value matters.
* When you write a role, <code>PermissionController.get_enum()</code> constrains the <code>permissions</code> field to known slugs; an unknown slug fails validation. See [[References/Role]].

{{Related}}