Scopes & Role-Based Access Control

Health Gorilla uses OAuth 2.0 scopes and role-based access control (RBAC) to manage and enforce fine-grained access to APIs. This ensures that clients and users can only perform actions explicitly authorized for them.

OAuth Scopes

OAuth scopes define what a token can access. When requesting a token, you must include the appropriate scopes. If a token lacks the required scope, the API will return a 403 Forbidden error.

Common Scopes

ScopeDescription
user/.Full user-level access to all FHIR resources
patient/*.readRead-only access to all patient resources
patient/*.writeWrite access to patient resources
user/Observation.readRead Observation resources
user/MedicationRequest.writeCreate MedicationRequest entries
patient360Access Patient360 aggregated longitudinal data

Scope-Based Access Examples

Read Patient Data

GET /fhir/Patient/{id}
Authorization: Bearer {access_token}
Required Scope: patient/*.read

Submit Medication Request

POST /fhir/MedicationRequest
Authorization: Bearer {access_token}
Content-Type: application/json
Example Payload
{
  "resourceType": "MedicationRequest",
  "status": "active",
  "intent": "order",
  "medicationCodeableConcept": {
    "text": "Atorvastatin 40mg Tablet"
  },
  "subject": {
    "reference": "Patient/{patient_id}"
  }
}
Required Scope: user/MedicationRequest.write

Role-Based Access Control (RBAC)

In addition to scopes, Health Gorilla enforces role-based access rules tied to user accounts. This adds a layer of security by ensuring users can only act within the boundaries of their assigned roles.

User Roles and Permissions

RoleAllowed Actions
PhysicianFull read/write access to patient records
NurseRetrieve and update patient data, but cannot create medication requests
Administrative UserAccess limited to demographic and billing data
System IntegrationServer-based access with explicitly defined scopes only

Tokens are evaluated based on both the granted scopes and the user or client’s role. A user may have the correct scope but still be denied if their role is too restrictive.