SMART on FHIR Scopes Explained: A Plain-English Reference

SMART on FHIR scopes define what a third-party application can access through your FHIR APIs. Every scope is a permission boundary: it specifies the data, the context, and the operation.

The syntax is compact but dense. If you're implementing SMART on FHIR for the first time, or reviewing scope configurations for compliance, having a clear reference saves hours of digging through spec documents.

This page covers the scope format, every context type, the most common FHIR resource types, and real-world examples of scope strings you'll encounter in production.

Scope Syntax

Every SMART on FHIR scope follows the same pattern:

context/ResourceType.permission

Three parts, separated by a slash and a dot:

Part	What it defines	Values
Context	Whose data is being accessed	patient, user, system
ResourceType	Which FHIR resource	Any FHIR R4 resource type (e.g., Patient, Observation)
Permission	What the application can do	read, write, * (both)

A wildcard * can replace the ResourceType to request access to all resources within a context: patient/*.read means read access to all FHIR resources for a specific patient.

Context Types

The context is the first part of the scope string. It determines the access boundary.

patient

Access is scoped to a single patient who authorized it. The application can only access data for the patient who granted consent during the OAuth flow.

When it's used: Patient-facing mobile apps, personal health record applications, wellness apps that read health data with the patient's permission.

Example scopes:

• patient/Observation.read - read lab results, vitals, and other observations for this patient
• patient/MedicationRequest.read - read medication prescriptions for this patient
• patient/Condition.read - read diagnoses and conditions for this patient

Key constraint: The application cannot access data for any other patient, even if those patients have also authorized access. Each authorization is independent.

user

Access is scoped to what the logged-in user is allowed to see. The application inherits the user's permissions. A clinician using an application with user/Patient.read can see patients assigned to them but not the entire patient database.

When it's used: Provider-facing applications where a clinician or care coordinator is logged in. EHR-embedded apps. Clinical decision support tools.

Example scopes:

• user/Patient.read - read patient records the logged-in user has access to
• user/Encounter.read - read encounter records within the user's access level
• user/DocumentReference.write - create documents on behalf of the logged-in user

Key constraint: Access depends on the user's role and permissions in the underlying system. The scope grants the application access to those resources, but the application can't exceed what the user themselves would see.

system

Access is not tied to a specific patient or user. The application operates as a backend service with broad access, authorized by the system administrator rather than an individual.

When it's used: Backend data pipelines, population health analytics, payer-to-payer data exchange, bulk data export, automated reporting.

Example scopes:

• system/Patient.read - read all patient records
• system/ExplanationOfBenefit.read - read all claims and benefits data
• system/Coverage.read - read all insurance coverage records

Key constraint: System-level scopes are the most powerful and the most dangerous. They bypass patient consent and user-level access controls. Granting system-level scopes should always require explicit approval, and the applications that hold them should be monitored closely.

Common FHIR Resource Types and Their Scopes

FHIR R4 defines over 150 resource types. In practice, most applications request scopes for a much smaller set. Here are the resource types you'll encounter most often, organized by category.

Patient demographics and identity

Resource	What it contains	Common scopes
Patient	Name, DOB, gender, address, identifiers	patient/Patient.read, system/Patient.read
RelatedPerson	Caregivers, guardians, emergency contacts	patient/RelatedPerson.read
Person	Cross-record identity linkage	system/Person.read

Clinical data

Resource	What it contains	Common scopes
Observation	Lab results, vitals, social history, assessments	patient/Observation.read
Condition	Diagnoses, problems, health concerns	patient/Condition.read
Procedure	Surgeries, treatments, interventions	patient/Procedure.read
DiagnosticReport	Pathology, radiology, and other diagnostic reports	patient/DiagnosticReport.read
DocumentReference	Clinical notes, discharge summaries, imaging reports	patient/DocumentReference.read

Medications

Resource	What it contains	Common scopes
MedicationRequest	Prescriptions and medication orders	patient/MedicationRequest.read
MedicationDispense	Pharmacy dispensing records	patient/MedicationDispense.read
Immunization	Vaccination records	patient/Immunization.read

Encounters and care coordination

Resource	What it contains	Common scopes
Encounter	Visits, admissions, telehealth sessions	patient/Encounter.read, user/Encounter.read
CarePlan	Treatment plans and care coordination	patient/CarePlan.read
CareTeam	Providers involved in a patient's care	patient/CareTeam.read

Financial and administrative

Resource	What it contains	Common scopes
Coverage	Insurance plan details, member IDs	patient/Coverage.read, system/Coverage.read
ExplanationOfBenefit	Claims, adjudication, payment details	patient/ExplanationOfBenefit.read
Claim	Submitted claims for services	system/Claim.read

Prior authorization (CMS-0057-F)

Resource	What it contains	Common scopes
ClaimResponse	Prior authorization decisions	patient/ClaimResponse.read, system/ClaimResponse.read
Task	Prior authorization request tracking	system/Task.read, system/Task.write

Real-World Scope Sets by Application Type

Applications don't request scopes one at a time. They request a set of scopes that matches their use case. Here are typical scope sets for common healthcare application types.

Patient health record app

A mobile app that lets patients view their health data.

patient/Patient.read
patient/Observation.read
patient/Condition.read
patient/MedicationRequest.read
patient/Immunization.read
patient/Encounter.read
patient/DocumentReference.read

This set gives the app read access to the patient's demographics, clinical data, medications, immunizations, encounters, and documents. No write access. No system-level access.

Wellness and fitness integration

An app that reads vitals and activity data to provide health insights.

patient/Observation.read

One scope. This app only needs observations (which include vitals, lab results, and activity data). It doesn't need medications, conditions, or demographics. A well-scoped application requests the minimum it needs.

Provider clinical tool

An EHR-embedded tool used by clinicians to review and document patient care.

user/Patient.read
user/Encounter.read
user/Condition.read
user/Observation.read
user/DocumentReference.write

User-level context means the app inherits the clinician's access level. Write access is limited to document creation (clinical notes).

Payer-to-payer data exchange

A backend service that transfers patient data when members switch health plans (CMS-0057-F requirement).

system/Patient.read
system/Coverage.read
system/ExplanationOfBenefit.read
system/Condition.read
system/MedicationRequest.read
system/Encounter.read

System-level context because there's no user or patient in the loop. This is a backend-to-backend exchange authorized at the organizational level.

Prior authorization processor

A system that submits and tracks prior authorization requests.

system/ClaimResponse.read
system/Task.read
system/Task.write
system/Patient.read
system/Coverage.read

Write access to Task resources allows the application to create and update prior authorization requests. Read access to ClaimResponse provides the authorization decisions.

SMART on FHIR Scopes v2

SMART on FHIR v2 (part of SMART App Launch 2.0) introduces finer-grained scope syntax. Instead of just read and write, v2 supports specific FHIR interactions:

v1 permission	v2 equivalents
read	rs (read + search)
write	cud (create + update + delete)
*	cruds (create + read + update + delete + search)

v2 also adds scope filtering with search parameters, allowing scopes like patient/Observation.rs?category=vital-signs to limit access to only vital sign observations rather than all observations.

v2 is not yet required by CMS-0057-F, but it's the direction the standard is heading. If you're implementing scope management now, design your system to accommodate the v2 syntax in the future.

Common Scope Management Mistakes

Mistakes in scope configuration are some of the most common compliance findings. Here are the ones that come up repeatedly.

• Granting patient/*.read when specific resources would suffice. A wellness app doesn't need access to conditions, medications, and clinical notes. Grant the specific resource scopes it needs. Wildcard resource scopes should be rare and justified.
• Using system context when user or patient would work. System-level scopes bypass individual access controls. Only use them for backend services that genuinely need cross-patient access.
• Not enforcing scopes at the API layer. Scopes in the token are meaningless if your API doesn't check them. Every endpoint should validate that the presented token includes the required scope for that resource and operation.
• Never reviewing granted scopes. Scopes granted during initial registration become permanent by default. Periodic review is the only way to catch over-scoping, orphaned access, and applications that no longer need what they were originally granted.
• Mixing up read and write scope implications. Write scopes are significantly more sensitive than read scopes. An application with patient/Condition.write can add diagnoses to a patient's record. Grant write scopes only when the application genuinely needs to create or modify data.

For a walkthrough of how these mistakes compound into compliance failures, see managing API scopes manually is a compliance disaster waiting to happen.

Using This Reference

Bookmark this page. Use the resource tables when configuring scope requirements for new applications. Use the application-type examples as templates for scope sets. Use the common mistakes section as a review checklist before approving scope grants.

For the broader picture of how scope management fits into your API program, see the complete guide to API scope management. For understanding what SMART on FHIR is and how it works, start there.

Apiable manages SMART on FHIR scope assignments as part of its partner onboarding and access control workflows. Scopes are declared during application registration, validated against your policies, and enforced through your API gateway. Book a demo to see how it works.