Consent Resource

FHIR’s Consent resource allows patients to control how their data is used and shared. ESUS uses consent records to gate access to PHI resources — the ABAC engine checks for an active Consent record with scope "treatment" before allowing non-admin practitioners to read, update, or delete a patient’s sensitive data by ID.

scope is the field that unlocks clinical access. The access engine only recognizes the exact string "treatment". Without an active treatment consent, a non-admin clinician gets 403 Forbidden when accessing that patient’s PHI. Other scope values are stored but do not enable clinical PHI access.

Create a Consent (treatment)

scope is a required plain string (max 50 characters), not a CodeableConcept object. To enable clinical PHI access, use "treatment":

curl -X POST https://api.esus.health/fhir/Consent \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Consent",
    "status": "active",
    "scope": "treatment",
    "patientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "policy": [{
      "uri": "https://esus.health/privacy-policy"
    }]
  }'

Consent Status

Other Consent Scopes

You can record consents with other scope values (e.g. "research") for your own governance purposes. scope is still a plain string:

curl -X POST https://api.esus.health/fhir/Consent \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Consent",
    "status": "active",
    "scope": "research",
    "patientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "provision": {
      "type": "permit",
      "purpose": [{
        "system": "http://terminology.hl7.org/CodeSystem/v3-ActReason",
        "code": "HRESCH",
        "display": "Health Research"
      }]
    }
  }'

Only "treatment" affects PHI access control. A consent with scope "research" (or any other value) is stored but does not enable clinical PHI access: the access check looks exclusively for an active treatment consent. The provision.actor / provision.type: "deny" blocks are stored but are not evaluated by the access engine — consent cannot allow or deny a specific practitioner or organization.

Revoke Consent

To revoke access, update the treatment consent’s status to inactive (or rejected). As soon as no active treatment consent exists for the patient in your organization, non-admin clinicians get 403 when accessing their PHI:

curl -X PUT https://api.esus.health/fhir/Consent/c1a2e3d4-5b6f-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Consent",
    "status": "inactive",
    "scope": "treatment",
    "patientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }'

Query Consent Records

# Get all active consents for a patient
# The `patient` parameter is a bare UUID (NOT the "Patient/<id>" form)
curl "https://api.esus.health/fhir/Consent?patient=3fa85f64-5717-4562-b3fc-2c963f66afa6&status=active" \
  -H "Authorization: Bearer TOKEN"

The supported search filters are patient (bare UUID) and status.

How Consent Gates PHI Access

When a non-admin practitioner requests a PHI resource by ID (e.g., GET /fhir/Observation/aa11bb22-cc33-dd44-ee55-ff6677889900), the ABAC engine:

1. Verifies the practitioner has the read permission for Observation
2. Resolves the patient linked to that Observation
3. Queries the Consent table filtering by patientId + status='active' + organizationId, and checks whether any has scope "treatment"
4. If no active treatment consent exists for the patient in that organization → returns 403 Forbidden with a FHIR OperationOutcome

This check happens automatically — you do not need to implement it in your application. It applies to reads, updates, and deletes of PHI resources by ID; searches and creates are exempt from the consent check. Users with the admin role bypass it entirely.