Authorization Scopes
What are scopes?
In SMART-on-FHIR (and OAuth in general) a 'scope' is a way to limit an app’s access to a user’s data. Rather than granting complete access to a user’s clinical data, it is preferable to give apps a way to request a more limited scope of what data they are allowed to access.
Some apps only need to identify the user and retrieve patient demographics, so they only need access to a user ID and basic identifying information. Other apps may need to know more information such as a patient’s vital signs, or they may need broad access to an entire population and the ability to retrieve all medications and lab results.
The idea is that users will be more willing to authorize an application if they know exactly what the application can and cannot do with the data. Scopes are a way to control access and help the users to understand the permissions they are granting to the application.
It’s important to remember that scopes are not the same as the internal permissions system of Greenway Intergy, Prime Suite, Patient Portal, and SmartHub. Scopes are a way to limit what a SMART-on-FHIR application can do within the context of what a user can do.
For example, if you have a user who is not permitted to view clinical information in the EHR, and the application is requesting the user/Patient.read scope, the Authorization server is not going to permit calls to the /Patient resource to retrieve all Patients in the practice because that user is not allowed to access that data.
Another way to think of this is that 'scopes' are the permissions that the SMART-on-FHIR application requests from the user who wants to use the app.
SMART 1.0 Scopes Overview
SMART 1.0 introduced basic read/write scopes with limited granularity.
Scope Syntax
<context>/<resource or *>.<access>
- context: patient | user
- resource: FHIR resource name or * (wildcard)
- access: read | write | * (read + write)
Examples
- patient/Observation.read → Read-only access to patient’s Observations
- user/*.write → Write access to all resources in user context
- user/DocumentReference.* → Full access (read + write) to DocumentReference
See also SMART App Launch: Scopes and Launch Context
Note: Currently, our FHIR ecosystem does not support the writeback feature.
Greenway FHIR API Scopes (Smart 1.0 Format)
openid - Permission to retrieve information about the current logged-in user.
fhirUser - Permission to retrieve information about the current logged-in user.
online_access - Request a refresh_token that can be used to obtain a new access token to replace an expired one, and that will be usable for as long as the end-user remains online.
offline_access - Request a refresh_token that can be used to obtain a new access token to replace an expired one, even after the end-user no longer is online after the access token expires.
launch - Permission to obtain launch context when app is launched inside the EHR.
launch/patient - When launching outside the EHR, ask for a patient to be selected at launch time.
launch/encounter - When launching outside the EHR, ask for an encounter to be selected at launch time.
patient/AllergyIntolerance.read - Permission to read this resource for the current patient
patient/Binary.read - Permission to read this resource for the current patient
patient/CarePlan.read - Permission to read this resource for the current patient
patient/CareTeam.read - Permission to read this resource for the current patient
patient/Condition.read - Permission to read this resource for the current patient
patient/Coverage.read - Permission to read this resource for the current patient
patient/Device.read - Permission to read this resource for the current patient
patient/DiagnosticReport.read - Permission to read this resource for the current patient
patient/DocumentReference.read - Permission to read this resource for the current patient
patient/Encounter.read - Permission to read this resource for the current patient
patient/Goal.read - Permission to read this resource for the current patient
patient/Group.read - Permission to read this resource for the current patient
patient/Immunization.read - Permission to read this resource for the current patient
patient/Location.read - Permission to read this resource for the current patient
patient/Medication.read - Permission to read this resource for the current patient
patient/MedicationDispense.read - Permission to read this resource for the current patient
patient/MedicationRequest.read - Permission to read this resource for the current patient
patient/Observation.read - Permission to read this resource for the current patient
patient/Organization.read - Permission to read this resource for the current patient
patient/Patient.read - Permission to read this resource for the current patient
patient/Practitioner.read - Permission to read this resource for the current patient
patient/PractitionerRole.read - Permission to read this resource for the current patient
patient/Procedure.read - Permission to read this resource for the current patient
patient/Provenance.read - Permission to read this resource for the current patient
patient/RelatedPerson.read - Permission to read this resource for the current patient
patient/ServiceRequest.read - Permission to read this resource for the current patient
patient/Specimen.read - Permission to read this resource for the current patient
user/AllergyIntolerance.read - Permission to read any instance of this resource available to the current user
user/Binary.read - Permission to read any instance of this resource available to the current user
user/CarePlan.read - Permission to read any instance of this resource available to the current user
user/CareTeam.read - Permission to read any instance of this resource available to the current user
user/Condition.read - Permission to read any instance of this resource available to the current user
user/Coverage.read - Permission to read any instance of this resource available to the current user
user/Device.read - Permission to read any instance of this resource available to the current user
user/DiagnosticReport.read - Permission to read any instance of this resource available to the current user
user/DocumentReference.read - Permission to read any instance of this resource available to the current user
user/Encounter.read - Permission to read any instance of this resource available to the current user
user/Goal.read - Permission to read any instance of this resource available to the current user
user/Group.read - Permission to read any instance of this resource available to the current user
user/Immunization.read - Permission to read any instance of this resource available to the current user
user/Location.read - Permission to read any instance of this resource available to the current user
user/Medication.read - Permission to read any instance of this resource available to the current user
user/MedicationDispense.read - Permission to read any instance of this resource available to the current user
user/MedicationRequest.read - Permission to read any instance of this resource available to the current user
user/Observation.read - Permission to read any instance of this resource available to the current user
user/Organization.read - Permission to read any instance of this resource available to the current user
user/Patient.read - Permission to read any instance of this resource available to the current user
user/Practitioner.read - Permission to read any instance of this resource available to the current user
user/PractitionerRole.read - Permission to read any instance of this resource available to the current user
user/Procedure.read - Permission to read any instance of this resource available to the current user
user/Provenance.read - Permission to read any instance of this resource available to the current user
user/RelatedPerson.read - Permission to read any instance of this resource available to the current user
user/ServiceRequest.read - Permission to read any instance of this resource available to the current user
user/Specimen.read - Permission to read any instance of this resource available to the current user
SMART 2.0 Scopes Overview
SMART 2.0 introduces granular, flexible, and expressive scopes for controlling access to FHIR resources. This enables developers to request precise permissions for their apps, improving security and compliance.
What’s New in SMART 2.0?
- CRUDS Permissions
SMART 2.0 introduces operation-based scopes using the acronym CRUDS:
| Operation | Symbol | Description |
|---|---|---|
| Create | .c | Allows creation of new FHIR resources. |
| Read | .r | Allows reading/viewing of existing resources. |
| Update | .u | Allows modification of existing resources. |
| Delete | .d | Allows deletion of resources. |
| Search | .s | Allows searching/filtering of resources using FHIR search parameters. |
Examples of combined operations:
- .rs (read + search)
- .cud (create, update, delete)
- .cruds (all operations)
Note: Currently, our FHIR ecosystem does not support the writeback feature.
- Granular Scopes
Developers can append FHIR search parameters to limit data by category or filters.
Example: patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs
This scope allows read + search access to Observation resources only for Vital Signs.
SMART 2.0 Syntax
<context>/<resource or *>.<ops>[?search-params]
- context: patient | user | system
- resource: FHIR resource name or *
- ops: ordered subset of .cruds (e.g., .r, .rs, .cud, .cruds)
- search-params: optional FHIR search parameters
Example: patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs
Supported Granular Scopes
Condition sub-resources
Encounter Diagnosis, Problem List, and Health Concern:
- Search category for Encounter Diagnosis - category=http://terminology.hl7.org/CodeSystem/condition-category|encounter-diagnosis
- Search category for Problem List - category= category=http://terminology.hl7.org/CodeSystem/condition-category|problem-list-item
- Search category for Health Concern - category=http://hl7.org/fhir/us/core/CodeSystem/condition-category|health-concern
Observation sub-resources
Clinical Test, Laboratory, Social History, SDOH, Survey, and Vital Signs:
- Search category for Clinical Test - category=http://terminology.hl7.org/CodeSystem/observation-category|procedure
- Search category for Laboratory - category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory
- Search category for Social History - category=http://terminology.hl7.org/CodeSystem/observation-category|social-history
- Search category for SDOH - category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|sdoh
- Search category for Survey - category=http://terminology.hl7.org/CodeSystem/observation-category|survey
- Search category for Vital Signs - category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs
Backward Compatibility (SMART 1.0 → 2.0)
| SMART 1.0 | SMART 2.0 Equivalent |
|---|---|
| patient/Observation.read | patient/Observation.rs |
| user/*.write | user/*.cud |
| user/DocumentReference.* | user/DocumentReference.cruds |
See also SMART App Launch: Scopes and Launch Context
Greenway FHIR API Scopes (SMART 2.0 Format)
openid - Permission to retrieve information about the current logged-in user.
fhirUser - Permission to retrieve information about the current logged-in user.
online_access - Request a refresh_token that can be used to obtain a new access token to replace an expired one, and that will be usable for as long as the end-user remains online.
offline_access - Request a refresh_token that can be used to obtain a new access token to replace an expired one, even after the end-user no longer is online after the access token expires.
launch - Permission to obtain launch context when app is launched inside the EHR.
launch/patient - When launching outside the EHR, ask for a patient to be selected at launch time.
launch/encounter - When launching outside the EHR, ask for an encounter to be selected at launch time.
patient/AllergyIntolerance.rs - Permission to read this resource for the current patient
patient/Binary.rs - Permission to read this resource for the current patient
patient/CarePlan.rs - Permission to read this resource for the current patient
patient/CareTeam.rs - Permission to read this resource for the current patient
patient/Condition.rs - Permission to read this resource for the current patient
patient/Coverage.rs - Permission to read this resource for the current patient
patient/Device.rs - Permission to read this resource for the current patient
patient/DiagnosticReport.rs - Permission to read this resource for the current patient
patient/DocumentReference.rs - Permission to read this resource for the current patient
patient/Encounter.rs - Permission to read this resource for the current patient
patient/Goal.rs - Permission to read this resource for the current patient
patient/Group.rs - Permission to read this resource for the current patient
patient/Immunization.rs - Permission to read this resource for the current patient
patient/Location.rs - Permission to read this resource for the current patient
patient/Medication.rs - Permission to read this resource for the current patient
patient/MedicationDispense.rs - Permission to read this resource for the current patient
patient/MedicationRequest.rs - Permission to read this resource for the current patient
patient/Observation.rs - Permission to read this resource for the current patient
patient/Organization.rs - Permission to read this resource for the current patient
patient/Patient.rs - Permission to read this resource for the current patient
patient/Practitioner.rs - Permission to read this resource for the current patient
patient/PractitionerRole.rs - Permission to read this resource for the current patient
patient/Procedure.rs - Permission to read this resource for the current patient
patient/Provenance.rs - Permission to read this resource for the current patient
patient/RelatedPerson.rs - Permission to read this resource for the current patient
patient/ServiceRequest.rs - Permission to read this resource for the current patient
patient/Specimen.rs - Permission to read this resource for the current patient
user/AllergyIntolerance.rs - Permission to read any instance of this resource available to the current user
user/Binary.rs - Permission to read any instance of this resource available to the current user
user/CarePlan.rs - Permission to read any instance of this resource available to the current user
user/CareTeam.rs - Permission to read any instance of this resource available to the current user
user/Condition.rs - Permission to read any instance of this resource available to the current user
user/Coverage.rs - Permission to read any instance of this resource available to the current user
user/Device.rs - Permission to read any instance of this resource available to the current user
user/DiagnosticReport.rs - Permission to read any instance of this resource available to the current user
user/DocumentReference.rs - Permission to read any instance of this resource available to the current user
user/Encounter.rs - Permission to read any instance of this resource available to the current user
user/Goal.rs - Permission to read any instance of this resource available to the current user
user/Group.rs - Permission to read any instance of this resource available to the current user
user/Immunization.rs - Permission to read any instance of this resource available to the current user
user/Location.rs - Permission to read any instance of this resource available to the current user
user/Medication.rs - Permission to read any instance of this resource available to the current user
user/MedicationDispense.rs - Permission to read any instance of this resource available to the current user
user/MedicationRequest.rs - Permission to read any instance of this resource available to the current user
user/Observation.rs - Permission to read any instance of this resource available to the current user
user/Organization.rs - Permission to read any instance of this resource available to the current user
user/Patient.rs - Permission to read any instance of this resource available to the current user
user/Practitioner.rs - Permission to read any instance of this resource available to the current user
user/PractitionerRole.rs - Permission to read any instance of this resource available to the current user
user/Procedure.rs - Permission to read any instance of this resource available to the current user
user/Provenance.rs - Permission to read any instance of this resource available to the current user
user/RelatedPerson.rs - Permission to read any instance of this resource available to the current user
user/ServiceRequest.rs - Permission to read any instance of this resource available to the current user
user/Specimen.rs - Permission to read any instance of this resource available to the current user
Updated about 10 hours ago