US Core Implementation Guide
8.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 8.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

SMART on FHIR Obligations and Capabilities

Page standards status: Trial-use

This page is updated content for version 7.0.0

SMART App Launch Implementation Guide Release 2.0.0 describes a set of foundational patterns based on OAuth 2.0 for client applications to authorize, authenticate, and integrate with FHIR-based data systems. This page documents the SMART on FHIR obligations and capabilities for US Core Servers supporting User-Facing Applications and Backend Services.

Capability Sets for US Core Servers Supporting User-Facing Applications and Backend Services

To promote interoperability, SMART on FHIR defines a set of core capabilities. An individual SMART server will publish a granular list of its capabilities, and a set of these capabilities is combined to support a specific use, a Capability Set. See SMART App Launch's FHIR OAuth authorization Endpoints and Capabilities for more details. Servers MAY support the other SMART on FHIR Capability Sets and capabilities than those listed below.

Capabilities for Implementations Supporting User-Facing Applications

At least one of the following SMART on FHIR Capability Sets SHOULD be supported for US Core Servers that support User-Facing Applications. For certified systems, both SHALL be supported:

Capabilities for Implementations Supporting Backend Services

Implementations supporting Backend Services – for example, to meet US EHR certification requirements - SHALL include support for the client-confidential-asymmetric capability and system/scopes.

US Core Servers SHALL Support Token Introspection

US Core Server SHALL support token introspection defined by the SMART App Launch Guide. For more details and additional consideration, see SMART App Launch's Token Introspection.

SMART Scopes

SMART's scopes, defined in Version 2.0.0 of the SMART App Launch implementation guide, allow access permissions to be delegated to a client application. The US Core API requires servers to support resource level scopes and granular scopes, allowing access to specific data about a single patient. US Core's required scopes (SHALL) are based on community-based consensus that the scope meets a system requirement, clinical need, or federal regulation. Similarly, US Core's recommended scopes (SHOULD) rely on community-based consensus that the scope meets a system requirement or clinical need as a best practice.

The US Core required scopes listed below are named in the HTI-1 final rule, which requires support for the Condition and Observation category scopes. (Note that although mentioned in HTI-1 final rule, there is no "Clinical Test" category for Observation in US Core.) The recommended granular scope listed below is of particular interest to patients and health systems. Implementations meeting US EHR certification requirements must support all US Core's required scopes. Other systems only need to support scopes for the US Core APIs they support.

Each US Core Profile page includes a "Quick Start" section summarizing each profile's supported search transactions and scopes. Servers MAY support other scopes in addition to those listed below and in the Quick Start sections. 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". Note that a granular scope grants access to all resources matching that granular scope regardless of whether other categories are present.

Scopes Format

SMART App Launch Version 2.0.0 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 patient-specific scope:

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

This example uses a patient/ prefix, but implementers may support system/ and user/.

US Core Scopes

The table below summarizes the US Core scope requirements (SHALL) and best practice recommendations (SHOULD) for resource-level and granular scopes. This information can be found for each US Core Profile in the profile page's "Quick Start" section.

For "User-Facing Applications", a system's support for patient-level (patient) or user-level (user) scopes depends on its published list of SMART on FHIR capabilities (see the capability sets above). For example, if a server lists permission-patient and permission-user in its capabilities, it SHALL support both patient-level and user-level required scopes and SHOULD support both patient-level and user-level recommended best-practice scopes.

For "Backend-Services", System-level scopes (system) describe data that a client system is directly authorized to access. Systems that support system-level (system) scopes SHALL support the required US Core scopes and SHOULD support the recommended US Core scopes.

The Following Resource Level Scopes SHALL Be Supported
Resource Type Resource Level Scope
AllergyIntolerance <patient|user|system>/AllergyIntolerance.rs
CarePlan <patient|user|system>/CarePlan.rs
CareTeam <patient|user|system>/CareTeam.rs
Condition <patient|user|system>/Condition.rs
Coverage <patient|user|system>/Coverage.rs
Device <patient|user|system>/Device.rs
DiagnosticReport <patient|user|system>/DiagnosticReport.rs
DocumentReference <patient|user|system>/DocumentReference.rs
Encounter <patient|user|system>/Encounter.rs
Goal <patient|user|system>/Goal.rs
Immunization <patient|user|system>/Immunization.rs
MedicationDispense <patient|user|system>/MedicationDispense.rs
MedicationRequest <patient|user|system>/MedicationRequest.rs
Observation <patient|user|system>/Observation.rs
Organization <patient|user|system>/Organization.rs
Patient <patient|user|system>/Patient.rs
Practitioner <patient|user|system>/Practitioner.rs
PractitionerRole <patient|user|system>/PractitionerRole.rs
Procedure <patient|user|system>/Procedure.rs
Provenance <patient|user|system>/Provenance.rs
QuestionnaireResponse <patient|user|system>/QuestionnaireResponse.rs
RelatedPerson <patient|user|system>/RelatedPerson.rs
ServiceRequest <patient|user|system>/ServiceRequest.rs
Specimen <patient|user|system>/Specimen.rs
The Following Resource Level Scopes MAY Be Supported
Resource Type Resource Level Scope
Location <patient|user|system>/Location.rs
Medication <patient|user|system>/Medication.rs
The Following Granular Scopes SHALL Be Supported
Resource Type Granular Scope
Condition <patient|user|system>/Condition.rs?category=http://hl7.org/fhir/us/core/CodeSystem/condition-category|health-concern
Condition <patient|user|system>/Condition.rs?category=http://terminology.hl7.org/CodeSystem/condition-category|encounter-diagnosis
Condition <patient|user|system>/Condition.rs?category=http://terminology.hl7.org/CodeSystem/condition-category|problem-list-item
Observation <patient|user|system>/Observation.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|sdoh
Observation <patient|user|system>/Observation.rs?category=http://terminology.hl7.org//CodeSystem-observation-category|social-history
Observation <patient|user|system>/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory
Observation <patient|user|system>/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|survey
Observation <patient|user|system>/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs
The Following Granular Scopes SHOULD Be Supported
Resource Type Granular Scope
DocumentReference <patient|user|system>/DocumentReference.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note

Servers SHALL support the following metadata in their /.well-known/smart-configuration

In addition to the capabilities defined in the server's CapabilityStatement, servers SHALL document their SMART capabilities in their Well-Known Uniform Resource Identifiers (URIs) JSON file.

Required SMART App Launch Metadata

The SMART App Launch guide requires the following JSON file metadata:

  • issuer (conditional)
  • jwks_uri (conditional)
  • authorization_endpoint
  • grant_types_supported
  • token_endpoint
  • capabilities
  • code_challenge_methods_supported

Additional US Core Requirements

US Core requires following additional metadata:

  • scopes_supported: Array of scopes a client may request.
    • The server SHALL list all the required US Core Scopes from the table above for the US Core Profiles they support in the scopes_supported array; additional scopes MAY be supported (so clients should not consider this array 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 asked for and registered.
  • introspection_endpoint: The URL to a server's introspection endpoint, which can be used to validate a token.
    • Servers SHALL document this endpoint in the file

Example .well-known/smart-configuration File

This example .well-known/smart-configuration file shows all the required and recommended metadata listed in SMART App Launch for a certified system supporting User-Facing Applications and Backend Services. The server lists all the required and recommended US Core scopes for both patient/, user/, and system/ in the scopes_supported metadata array. See the SMART App Launch Implementation Guide for more examples 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",
    "user/AllergyIntolerance.rs",
    "system/AllergyIntolerance.rs",
    "patient/CarePlan.rs",
    "user/CarePlan.rs",
    "system/CarePlan.rs",
    "patient/CareTeam.rs",
    "user/CareTeam.rs",
    "system/CareTeam.rs",
    "patient/Condition.rs",
    "user/Condition.rs",
    "system/Condition.rs",
    "patient/Coverage.rs",
    "user/Coverage.rs",
    "system/Coverage.rs",
    "patient/Device.rs",
    "user/Device.rs",
    "system/Device.rs",
    "patient/DiagnosticReport.rs",
    "user/DiagnosticReport.rs",
    "system/DiagnosticReport.rs",
    "patient/DocumentReference.rs",
    "user/DocumentReference.rs",
    "system/DocumentReference.rs",
    "patient/Encounter.rs",
    "user/Encounter.rs",
    "system/Encounter.rs",
    "patient/Goal.rs",
    "user/Goal.rs",
    "system/Goal.rs",
    "patient/Immunization.rs",
    "user/Immunization.rs",
    "system/Immunization.rs",
    "patient/MedicationDispense.rs",
    "user/MedicationDispense.rs",
    "system/MedicationDispense.rs",
    "patient/MedicationRequest.rs",
    "user/MedicationRequest.rs",
    "system/MedicationRequest.rs",
    "patient/Observation.rs",
    "user/Observation.rs",
    "system/Observation.rs",
    "patient/Organization.rs",
    "user/Organization.rs",
    "system/Organization.rs",
    "patient/Patient.rs",
    "user/Patient.rs",
    "system/Patient.rs",
    "patient/Practitioner.rs",
    "user/Practitioner.rs",
    "system/Practitioner.rs",
    "patient/PractitionerRole.rs",
    "user/PractitionerRole.rs",
    "system/PractitionerRole.rs",
    "patient/Procedure.rs",
    "user/Procedure.rs",
    "system/Procedure.rs",
    "patient/Provenance.rs",
    "user/Provenance.rs",
    "system/Provenance.rs",
    "patient/QuestionnaireResponse.rs",
    "user/QuestionnaireResponse.rs",
    "system/QuestionnaireResponse.rs",
    "patient/RelatedPerson.rs",
    "user/RelatedPerson.rs",
    "system/RelatedPerson.rs",
    "patient/ServiceRequest.rs",
    "user/ServiceRequest.rs",
    "system/ServiceRequest.rs",
    "patient/Specimen.rs",
    "user/Specimen.rs",
    "system/Specimen.rs",
    "patient/Condition.rs?category=bar",
    "user/Condition.rs?category=bar",
    "system/Condition.rs?category=bar",
    "patient/Condition.rs?category=foo",
    "user/Condition.rs?category=foo",
    "system/Condition.rs?category=foo",
    "patient/Condition.rs?category=http://hl7.org/fhir/us/core/CodeSystem/condition-category|health-concern",
    "user/Condition.rs?category=http://hl7.org/fhir/us/core/CodeSystem/condition-category|health-concern",
    "system/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",
    "user/Condition.rs?category=http://terminology.hl7.org/CodeSystem/condition-category|encounter-diagnosis",
    "system/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",
    "user/Condition.rs?category=http://terminology.hl7.org/CodeSystem/condition-category|problem-list-item",
    "system/Condition.rs?category=http://terminology.hl7.org/CodeSystem/condition-category|problem-list-item",
    "patient/DiagnosticReport.rs?category=http://loinc.org|LP29684-5",
    "user/DiagnosticReport.rs?category=http://loinc.org|LP29684-5",
    "system/DiagnosticReport.rs?category=http://loinc.org|LP29684-5",
    "patient/DiagnosticReport.rs?category=http://loinc.org|LP29708-2",
    "user/DiagnosticReport.rs?category=http://loinc.org|LP29708-2",
    "system/DiagnosticReport.rs?category=http://loinc.org|LP29708-2",
    "patient/DiagnosticReport.rs?category=http://loinc.org|LP7839-6",
    "user/DiagnosticReport.rs?category=http://loinc.org|LP7839-6",
    "system/DiagnosticReport.rs?category=http://loinc.org|LP7839-6",
    "patient/DiagnosticReport.rs?category=http://terminology.hl7.org/CodeSystem/v2-0074|LAB",
    "user/DiagnosticReport.rs?category=http://terminology.hl7.org/CodeSystem/v2-0074|LAB",
    "system/DiagnosticReport.rs?category=http://terminology.hl7.org/CodeSystem/v2-0074|LAB",
    "patient/DocumentReference.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note",
    "user/DocumentReference.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note",
    "system/DocumentReference.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note",
    "patient/Observation.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|cognitive-status",
    "user/Observation.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|cognitive-status",
    "system/Observation.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|cognitive-status",
    "patient/Observation.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|disability-status",
    "user/Observation.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|disability-status",
    "system/Observation.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|disability-status",
    "patient/Observation.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|functional-status",
    "user/Observation.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|functional-status",
    "system/Observation.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|functional-status",
    "patient/Observation.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|sdoh",
    "user/Observation.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|sdoh",
    "system/Observation.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|sdoh",
    "patient/Observation.rs?category=http://terminology.hl7.org//CodeSystem-observation-category|social-history",
    "user/Observation.rs?category=http://terminology.hl7.org//CodeSystem-observation-category|social-history",
    "system/Observation.rs?category=http://terminology.hl7.org//CodeSystem-observation-category|social-history",
    "patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|activity",
    "user/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|activity",
    "system/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|activity",
    "patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|imaging",
    "user/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|imaging",
    "system/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|imaging",
    "patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory",
    "user/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory",
    "system/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|laboratory",
    "patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|procedure",
    "user/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|procedure",
    "system/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|procedure",
    "patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|survey",
    "user/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|survey",
    "system/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|survey",
    "patient/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs",
    "user/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs",
    "system/Observation.rs?category=http://terminology.hl7.org/CodeSystem/observation-category|vital-signs",
    "patient/ServiceRequest.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|functional-status",
    "user/ServiceRequest.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|functional-status",
    "system/ServiceRequest.rs?category=http://hl7.org/fhir/us/core/CodeSystem/us-core-category|functional-status",
    "patient/ServiceRequest.rs?category=http://snomed.info/sct|surgical-procedure",
    "user/ServiceRequest.rs?category=http://snomed.info/sct|surgical-procedure",
    "system/ServiceRequest.rs?category=http://snomed.info/sct|surgical-procedure"
],
  "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-user",
    "permission-v2",
    "client-public",
    "client-confidential-symmetric",
    "client-confidential-asymmetric",
    "context-ehr-patient",
    "sso-openid-connect"
  ]
}