US Core Implementation Guide
7.0.0-ballot - Ballot United States of America flag

US Core Implementation Guide, published by HL7 International / Cross-Group Projects. This guide is not an authorized publication; it is the continuous build for version 7.0.0-ballot built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/US-Core/ and changes regularly. See the Directory of published versions

US Core SMART Scopes

Page standards status: Informative

This page is new content for US Core Version 7.0.0

To meet the ONC’s granular scope requirement in HTI-1 proposed rule, the US Core API requires servers to support both resource level scopes and granular scopes as defined in Version 2.0.0 of SMART App Launch. US Core clients should follow the principle of least privilege and access only the necessary resources. In other words, if a client needs only vital sign observations, it should request access only to Observations with a category of “vital-signs”. US Core requires scopes for:

  1. specific data types defined in US Core and
  2. those of particular interest to US citizens and health systems.

SMART Scopes

In addition to the read and search capabilities defined in the server’s CapabilityStatement, servers SHALL document supported scopes in the scopes_supported section of a .well-known/smart-configuration capabilities array.

Scopes Format

Version 2.0.0 of SMART App Launch introduced a scope syntax of: <patient|user|system> / <fhir-resource>. <c | r | u | d |s> [?param=value]

For example, to limit read and search access to a specific patient’s laboratory observations but not other observations, the server grants the following scope:

patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory.

The example scopes below use a single FHIR search parameter of category applied to Condition and Observation. They use a patient/ prefix, but implementers can also support system/ and user/.

  • patient/Condition.rs?category=http://terminology.hl7.org/CodeSystem/condition-category|encounter-diagnosis
  • patient/Condition.rs?category=http://terminology.hl7.org/CodeSystem/condition-category|problem-list-item
  • patient/Condition.rs?category=http://hl7.org/fhir/us/core/CodeSystem/condition-category|health-concern
  • patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|clinical-test
  • patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory

US Core Scopes

The table below summarizes the US Core scope requirements. The same information can be found in each US Core Profile page’s “Quick Start” section.

US Core Profile Scopes
US Core AllergyIntolerance Profile resource level scope: patient/AllergyIntolerance.rs
US Core CarePlan Profile resource level scope: patient/CarePlan.rs
US Core CareTeam Profile resource level scope: patient/CareTeam.rs
US Core Condition Encounter Diagnosis Profile resource level scope: patient/Condition.rs
granular scope: patient.Condition.rs?category=http://terminology.hl7.org/CodeSystem/condition-category|encounter-diagnosis
US Core Condition Problems and Health Concerns Profile resource level scope: patient/Condition.rs
granular scope: patient.Condition.rs?category=http://terminology.hl7.org/CodeSystem/condition-category|problem-list-item
granular scope: patient.Condition.rs?category=http://hl7.org/fhir/us/core/CodeSystem/condition-category|health-concern`
US Core Coverage Profile resource level scope: patient/Coverage.rs
US Core Implantable Device Profile resource level scope: patient/Device.rs
US Core DiagnosticReport Profile for Report and Note Exchange resource level scope: patient/DiagnosticReport.rs
granular scope: patient.DiagnosticReport.rs?category=http://loinc.org|LP29684-5
granular scope: patient.DiagnosticReport.rs?category=http://loinc.org|LP29708-2
granular scope: patient.DiagnosticReport.rs?category=http://loinc.org|LP7839-6
US Core DiagnosticReport Profile for Laboratory Results Reporting resource level scope: patient/DiagnosticReport.rs
granular scope: patient.DiagnosticReport.rs?category=http://terminology.hl7.org/CodeSystem/v2-0074|LAB
US Core DocumentReference Profile resource level scope: patient/DocumentReference.rs
granular scope: patient.DocumentReference.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note
US Core Encounter Profile resource level scope: patient/Encounter.rs
US Core Goal Profile resource level scope: patient/Goal.rs
US Core Immunization Profile resource level scope: patient/Immunization.rs
US Core MedicationRequest Profile resource level scope: patient/MedicationRequest.rs
US Core MedicationDispense Profile resource level scope: patient/MedicationDispense.rs
US Core Laboratory Result Observation Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory
US Core Observation Pregnancy Status Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://terminology.hl7.org//CodeSystem-observation-category.html|social-history
US Core Observation Pregnancy Intent Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://terminology.hl7.org//CodeSystem-observation-category.html|social-history
US Core Observation Occupation Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://terminology.hl7.org//CodeSystem-observation-category.html|social-history
US Core Respiratory Rate Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs
US Core Simple Observation Profile resource level scope: patient/Observation.rs
US Core Heart Rate Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs
US Core Body Temperature Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs
US Core Pediatric Weight for Height Observation Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs
US Core Pulse Oximetry Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs
US Core Smoking Status Observation Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://terminology.hl7.org//CodeSystem-observation-category.html|social-history
US Core Observation Sexual Orientation Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://terminology.hl7.org//CodeSystem-observation-category.html|social-history
US Core Head Circumference Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs
US Core Body Height Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs
US Core BMI Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs
US Core Observation Screening Assessment Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|survey
US Core Average Blood Pressure Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs
US Core Blood Pressure Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs
US Core Observation Clinical Result Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|imaging
granular scope: patient.Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|procedure
granular scope: patient.Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory
US Core Pediatric BMI for Age Observation Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs
US Core Pediatric Head Occipital Frontal Circumference Percentile Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs
US Core Body Weight Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs
US Core Vital Signs Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs
US Core Organization Profile resource level scope: patient/Organization.rs
US Core Patient Profile resource level scope: patient/Patient.rs
US Core Practitioner Profile resource level scope: patient/Practitioner.rs
US Core PractitionerRole Profile resource level scope: patient/PractitionerRole.rs
US Core Procedure Profile resource level scope: patient/Procedure.rs
US Core Provenance Profile resource level scope: patient/Provenance.rs
US Core QuestionnaireResponse Profile resource level scope: patient/QuestionnaireResponse.rs
US Core RelatedPerson Profile resource level scope: patient/RelatedPerson.rs
US Core ServiceRequest Profile resource level scope: patient/ServiceRequest.rs
granular scope: patient.ServiceRequest.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|sdoh
granular scope: patient.ServiceRequest.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|functional-status
granular scope: patient.ServiceRequest.rs?category=http://snomed.info/sct|surgical-procedure
US Core Specimen Profile resource level scope: patient/Specimen.rs
US Core Treatment Intervention Preference Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|treatment-intervention-preference
US Core Care Experience Preference Profile resource level scope: patient/Observation.rs
granular scope: patient.Observation.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|care-experience-preference

US Core Server Obligations

The scopes are formally defined in a server hosts a smart-configuration file at [url]/.well-known/smart-configuration that is available to both authenticated and unauthenticated clients.

  • The server SHALL support all scopes listed in the table above for the US Core Profiles they support; additional scopes MAY be supported (so clients should not consider this an exhaustive list).

  • Servers MAY limit clients’ scopes to those configured at registration time. Servers SHALL allow users to select a subset of the requested scopes at the approval time. The app SHOULD inspect the returned scopes and accommodate the differences from the scopes it requested and registered.

Example .well-known/smart-configuration File

This example .well-known/smart-configuration file contains all the US Core scopes listed in the capabilities array. See the SMART App Launch Implementation Guide for more example and details.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "issuer": "https://ehr.example.com",
  "jwks_uri": "https://ehr.example.com/.well-known/jwks.json",
  "authorization_endpoint": "https://ehr.example.com/auth/authorize",
  "token_endpoint": "https://ehr.example.com/auth/token",
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "private_key_jwt"
  ],
  "grant_types_supported": [
    "authorization_code",
    "client_credentials"
  ],
  "registration_endpoint": "https://ehr.example.com/auth/register",
  "scopes_supported": [
    "openid",
    "profile",
    "launch",
    "launch/patient",
    "offline_access",
    "patient/AllergyIntolerance.rs",
    "patient/CarePlan.rs",
    "patient/CareTeam.rs",
    "patient/Condition.rs",
    "patient/Condition.rs?category=http://hl7.org/fhir/us/core/CodeSystem/condition-category|health-concern`",
    "patient/Condition.rs?category=http://terminology.hl7.org/CodeSystem/condition-category|encounter-diagnosis",
    "patient/Condition.rs?category=http://terminology.hl7.org/CodeSystem/condition-category|problem-list-item",
    "patient/Coverage.rs",
    "patient/Device.rs",
    "patient/DiagnosticReport.rs",
    "patient/DiagnosticReport.rs?category=http://loinc.org|LP29684-5",
    "patient/DiagnosticReport.rs?category=http://loinc.org|LP29708-2",
    "patient/DiagnosticReport.rs?category=http://loinc.org|LP7839-6",
    "patient/DiagnosticReport.rs?category=http://terminology.hl7.org/CodeSystem/v2-0074|LAB",
    "patient/DocumentReference.rs",
    "patient/DocumentReference.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note",
    "patient/Encounter.rs",
    "patient/Goal.rs",
    "patient/Immunization.rs",
    "patient/MedicationDispense.rs",
    "patient/MedicationRequest.rs",
    "patient/Observation.rs",
    "patient/Observation.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|care-experience-preference",
    "patient/Observation.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|treatment-intervention-preference",
    "patient/Observation.rs?category=http://terminology.hl7.org//CodeSystem-observation-category.html|social-history",
    "patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|imaging",
    "patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory",
    "patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|procedure",
    "patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|survey",
    "patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs",
    "patient/Organization.rs",
    "patient/Patient.rs",
    "patient/Practitioner.rs",
    "patient/PractitionerRole.rs",
    "patient/Procedure.rs",
    "patient/Provenance.rs",
    "patient/QuestionnaireResponse.rs",
    "patient/RelatedPerson.rs",
    "patient/ServiceRequest.rs",
    "patient/ServiceRequest.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|functional-status",
    "patient/ServiceRequest.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|sdoh",
    "patient/ServiceRequest.rs?category=http://snomed.info/sct|surgical-procedure",
    "patient/Specimen.rs"

  ],
  "response_types_supported": ["code"],
  "management_endpoint": "https://ehr.example.com/user/manage",
  "introspection_endpoint": "https://ehr.example.com/user/introspect",
  "revocation_endpoint": "https://ehr.example.com/user/revoke",
  "code_challenge_methods_supported": ["S256"],
  "capabilities": [
    "launch-ehr",
    "permission-patient",
    "permission-v2",
    "client-public",
    "client-confidential-symmetric",
    "context-ehr-patient",
    "sso-openid-connect"
  ]
}