SMART on FHIR Obligations and Capabilities

US Core Implementation Guide
7.0.0 - STU7 United States of America flag

This page is part of the US Core (v7.0.0: STU7) based on FHIR (HL7® FHIR® Standard) R4. This is the current published version. For a full list of available versions, see the Directory of published versions

Page standards status: Informative

Capability Sets for US Core Servers Supporting User-Facing Applications and Backend Services
US Core Servers SHALL Support Token Introspection
SMART Scopes
Servers SHALL support the following metadata in their /.well-known/smart-configuration

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”.

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

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

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

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

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 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 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"
  ]
}

IG © 2024+ HL7 International / Cross-Group Projects. Package hl7.fhir.us.core#7.0.0 based on FHIR 4.0.1. Generated 2024-05-08
Links: Table of Contents | QA Report | Version History | | Propose a change