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

Scope	Description
`user/.`	Full user-level access to all FHIR resources
`patient/*.read`	Read-only access to all patient resources
`patient/*.write`	Write access to patient resources
`user/Observation.read`	Read `Observation` resources
`user/MedicationRequest.write`	Create `MedicationRequest` entries
`patient360`	Access 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

Role	Allowed Actions
Physician	Full read/write access to patient records
Nurse	Retrieve and update patient data, but cannot create medication requests
Administrative User	Access limited to demographic and billing data
System Integration	Server-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.