Skip to content

Standardized API Certification Criterion at § 170.315(g)(10)

This section considers the HL7®1 FHIR® standardized API for patient and population services certification criterion, including all of the content contained in the ONC Cures Act Final Rule API preamble, the IFC API preamble, and the regulation paragraphs in § 170.315(g)(10).

Applicability

§ 170.315(g)(10) is applicable to all health IT developers who are certifying to the EHR base definition on or after December 31, 2022.

The API certification criterion finalized in § 170.315(g)(10) was included as part of the EHR Base Definition at § 170.102. While developers of health information technology are not required by the ONC to meet certification requirements, including certification requirements that are included as part of the EHR Base Definition, several federal, state and tribal entities, including Centers for Medicare & Medicaid Services, Centers for Disease Control and Prevention, and other programs reference the ONC Health IT Certification Program and require the use of certified health IT for program participation.

Health IT Feedback and Inquiry Portal

To submit questions or comments to ONC please use our Inquiry Portal. Anonymized versions of the § 170.315(g)(10) inquires and responses that ONC has handled through this portal can be accessed on the Health IT Feedback and Inquiry Portal: Standardized API Certification Criterion at § 170.315(g)(10) page.

Information and Clarifications

Entire Criterion

Clarifications included in the (g)(10) CCG that apply to the entire criterion

Clarifications:

Applies to all applicable base regulatory and SVAP standards:

  • On December 31, 2022, the Application Programming Interface (API) certification criterion in § 170.315(g)(10) replaces the “Application access—data category request” certification criterion (§ 170.315(g)(8)).
  • Health IT Modules are not required to support patient-facing API-enabled “read” services for multiple patients for the purposes of this certification criterion.
  • The clinical note text included in any of the notes described in the “Clinical Notes Guidance” section of the US Core Implementation Guide (IG) adopted in § 170.215(a)(2) must be represented in a “plain text” form, and it would be unacceptable for the note text to be converted to another file or format (e.g., .docx, PDF) when it is provided as part of an API response. The intent of this policy is to prohibit Health IT Modules from converting clinical notes from a “machine readable” format to a non-“machine readable” format (e.g., PDF). Clinical note text that originates from outside Health IT Modules should be exchanged using its original format. Additionally, “plain text” does not necessarily mean the FHIR® “contentType” “text/plain.”
  • The US Core IG Profile “StructureDefinition-us-core-patient” element “name.suffix” is required for testing and certification in the Certification Program to meet the USCDI requirement to support the “Patient Demographics” Data Class: “Suffix” Data Element.
  • A Health IT Module must support at least one Choice or Reference for US Core IG “must support” elements with multiple Choices or References, respectively.
  • A Health IT Module must be conformant to the US Core IG for all Choices and References included in its standardized API, and cannot misrepresent Choices via the standardized API (e.g. a Health IT Module cannot transform “integer” values to “string” values).
  • A health IT developer must document which US Core IG Choices and References are supported by their Health IT Module via public technical documentation to meet the requirements at § 170.315(g)(10)(viii) and the transparency conditions at § 170.404(a)(2).
  • Information originating from the (g)(10)-certified Health IT Module must conform to the requirements included in the criterion, but legacy information and information from outside systems is not required to be mapped to the USCDI “Applicable Standards” and the US Core IG terminologies and value sets. However, health IT developers are encouraged to exceed the minimum requirements described in § 170.315(g)(10) to support the mapping of legacy information to the terminologies and value sets included in the USCDI and US Core IG where possible.
  • In order to mitigate potential interoperability errors and inconsistent implementation of the Fast Healthcare Interoperability Resources (FHIR®) Bulk Data Access (Flat FHIR®) (v1.0.0: STU 1) standard, ONC assesses, approves, and incorporates corrections (errata) as part of required certification and testing to this criterion. Compliance with the following errata is necessary because the errata implements technical corrections and clarifications to the FHIR® Bulk Data Access (Flat FHIR®) (v1.0.0: STU 1) standard. There is a 90-day delay from the time the CCG has been updated with the ONC-approved errata to when compliance with the errata will be required to pass testing. Similarly, there will be an 18-month delay before a finding of an erratum’s absence in a Certified Health IT Module during surveillance would constitute a non-conformity under the Certification Program.

Applies to base regulatory standard USCDI v1 and US Core 3.1.1 or USCDI v1 and SVAP approved standard US Core 4.0.0:

  • The US Core IG Profile “StructureDefinition-us-core-patient” element “name.period” is required for testing and certification in the ONC Certification Program to meet the USCDI requirement to support the “Patient Demographics” data class: “Previous Name” data element.

Applies to SVAP approved standard US Core 5.0.1 and USCDI v2:

  • The US Core IG Profiles “StructureDefinition-us-core-patient” elements “name.use” and “name.period” are required for testing and certification in the ONC Certification Program to meet the USCDI requirement to support the “Patient Demographics” data class: “Previous Name” data element.
  • The US Core IG Profiles “StructureDefinition-us-core-patient” element “patient.address.use” and “patient.address.period” are required for testing and certification in the ONC Certification Program to meet the USCDI requirement to support the “Patient Demographics” data class: “Previous Address” data element.

Additional clarifications that apply to the entire (g)(10) criterion:

  • The API certification criterion in § 170.315(g)(10) replaces the “application access—data category request” certification criterion (§ 170.315(g)(8)) and supports API-enabled “read” services for single and multiple patients.
  • The term “services” includes all § 170.315(g)(10)-related technical capabilities included in a Health IT Module presented for testing and certification. The API-enabled “read” services for single patients is intended to support EHI requests and responses for individual patient records and the API-enabled “read” services for multiple patients is intended to support EHI requests and responses for multiple patients’ records.
  • The scope of patient cohorts for “population services” can include various groups defined at the discretion of the user of the API-enabled “read” services for multiple patients, including, for example, a group of patients that meet certain disease criteria or fall under a certain insurance plan.
  • The information blocking policies established by the ONC Cures Act Final Rule do not compel healthcare providers to implement Health IT Modules certified to requirements in § 170.315(g)(10).
  • While there may be slight variation between each instance of a Standardized API for patient and population services Health IT Module implemented by API Information Sources, ONC believes the standards that form the basis of the § 170.315(g)(10) certification criterion will enable interoperability across implementations.

Data Response (Single Patient)

Regulation text at § 170.315(g)(10)(i)(A)

(i) Data response. (A) Respond to requests for a single patient's data according to the standard adopted in § 170.215(a)(1) and implementation specification adopted in § 170.215(a)(2), including the mandatory capabilities described in “US Core Server CapabilityStatement,” for each of the data included in the standard adopted in § 170.213. All data elements indicated as “mandatory” and “must support” by the standards and implementation specifications must be supported.

Clarifications included in the (g)(10) CCG that apply to paragraph § 170.315(g)(10)(i)(A)

Technical outcome – Respond to requests for a single patient’s data according to the standard adopted in § 170.215(a)(1) and implementation specification adopted in § 170.215(a)(2), including the mandatory capabilities described in “US Core Server CapabilityStatement,” for each of the data included in the standard adopted in § 170.213. All data elements indicated as “mandatory” and “must support” by the standards and implementation specifications must be supported.

Clarifications:

Applies to all applicable base regulatory and SVAP standards:

  • All data elements and operations indicated as “mandatory” and “must support” by the standards and implementation specifications must be supported and are in-scope for testing.
  • Health IT Modules must support provenance according to the “Basic Provenance Guidance” section of the US Core IG.
  • For purposes of ONC Health IT Certification, health IT developers that always provide HL7® FHIR® “observation” values are not required to demonstrate Health IT Module support for “dataAbsentReason” elements. These include “dataAbsentReason” elements contained in the US Core implementation guide profiles and FHIR® Vital Sign profiles that build on the HL7® FHIR® “observation” and its derived profiles including HL7® FHIR® “observation-vitalsigns”, and HL7® FHIR® “observation-oxygensat”, including “component.dataAbsentReason” elements. However, health IT developers are still required to adhere to and demonstrate Health IT Module support for the “Missing Data” section of the US Core implementation guide.
  • For purposes of testing and certification, health IT developers are not required to demonstrate Health IT Module support for the “USCoreFetchDocumentReferences” ($docref) US Core IG operation.

Applies to base regulatory standard US Core 3.1.1

  • The HL7® Cross-Group Projects work group, through the US Core 'Patch' Process ticket FHIR-28393, approved patching US Core 3.1.1 to remove "must support" from the "DocumentReference.custodian" data element. For the purposes of testing and certification, health IT developers are not required to demonstrate Health IT Module support for the “custodian” data element in the “DocumentReference” US Core 3.1.1 IG Profile.

Applies to base regulatory standard US Core 3.1.1 and SVAP approved standard US Core 4.0.0:

  • For “Encounter,” “Organization,” and “Practitioner,” US Core IG profiles, only the “read” type interaction must be supported and will be included in testing and certification. For the “Location” FHIR® resource, Health IT Modules must either demonstrate support for the “read” type interaction or demonstrate support for providing the “Location” and FHIR® resource references as a contained resource. The “search” type interactions for these profiles and resource are not in scope for testing and certification. Health IT Modules must support these US Core IG profiles / FHIR® resource because they are included as “must support” data elements in US Core IG profiles required by the USCDI.
  • Health IT Modules must support provenance according to the “Basic Provenance Guidance” section of the US Core IG.

Applies to SVAP approved standard US Core 5.0.1 and USCDI v2:

  • For the “Organization” US Core IG profile, only the “read” type interaction must be supported and will be included in testing and certification. For the “Location” FHIR® resource, Health IT Modules must either demonstrate support for the “read” type interaction or demonstrate support for providing the “Location” FHIR® resource reference as a contained resource. The “search” type interactions for these profiles and resource are not in scope for testing and certification. Health IT Modules must support these US Core IG profiles / FHIR® resource because they are included as “must support” data elements in US Core IG profiles required by the United States Core Data for Interoperability (USCDI).
  • For purposes of testing and certification, health IT developers are not required to demonstrate Health IT Module support for the “QuestionnaireResponse” US Core IG profile.

Examples of “must support” in the US Core IG 3.1.1:

In US Core 3.1.1, the profile element Observation.value[x] contains the following Choices: Quantity, CodeableConcept, string, boolean, integer, Range, Ratio, SampledData, time, dateTime, Period A Health IT Module must support at least one of these Choices via the (g)(10) standardized API.

In US Core 3.1.1, the profile element Provenance.agent.who contains the following References: US Core Practitioner Profile, US Core Patient Profile, US Core Organization Profile A Health IT Module must support at least one of these References via the (g)(10) standardized API.

Additionally, a guided walk through of "must support" in FHIR and US Core 3.1.1 can be found on YouTube here.

Data Response (Multiple Patients)

Regulation text at § 170.315(g)(10)(i)(B)

(B) Respond to requests for multiple patients' data as a group according to the standard adopted in § 170.215(a)(1), and implementation specifications adopted in § 170.215(a)(2) and (4), for each of the data included in the standard adopted in § 170.213. All data elements indicated as “mandatory” and “must support” by the standards and implementation specifications must be supported.

Clarifications included in the (g)(10) CCG that apply to paragraph § 170.315(g)(10)(i)(B)

Technical outcome – Respond to requests for multiple patients’ data as a group according to the standard adopted in § 170.215(a)(1), and implementation specifications adopted in § 170.215(a)(2) and (4), for each of the data included in the standard adopted in § 170.213. All data elements indicated as “mandatory” and “must support” by the standards and implementation specifications must be supported.

Clarifications:

Applies to all applicable base regulatory and SVAP standards:

  • Health IT Modules may support scopes using either the system wildcard scope syntax or a list of system resource scopes, to enable the export of multiple patients’ data as a group.
  • During testing and certification for multiple patient services, Health IT Modules must demonstrate support for “Encounter,” “Organization,” and “Practitioner” US Core IG FHIR® Profiles.
  • Health IT Modules must demonstrate support for “Location” FHIR® resources by providing this resource as part of the multiple patient services response, or by including it as a contained resource as part of the multiple patient services response.
  • Health IT Modules must support provenance according to the “Basic Provenance Guidance” section of the US Core IG.

Supported Search Operations (Single Patient)

Regulation text at § 170.315(g)(10)(ii)(A)

(ii) Supported search operations. (A) Respond to search requests for a single patient's data consistent with the search criteria included in the implementation specification adopted in § 170.215(a)(2), specifically the mandatory capabilities described in “US Core Server CapabilityStatement.”

Clarifications included in the (g)(10) CCG that apply to paragraph § 170.315(g)(10)(ii)(A)

Technical outcome – Respond to search requests for a single patient’s data consistent with the search criteria included in the implementation specification adopted in § 170.215(a)(2), specifically the mandatory capabilities described in “US Core Server CapabilityStatement”.

Clarifications:

Applies to all applicable base regulatory and SVAP standards:

  • All data elements indicated as “mandatory” and “must support” by the standards and implementation specifications must be supported and are in scope for testing.
  • The § 170.315(g)(10) certification criterion requires Health IT Modules to support API-enabled “read” services for single and multiple patients. “Read” services include those that allow authenticated and authorized third-party applications to view EHI through a secure API. These services specifically exclude “write” capabilities, where authenticated and authorized third-party applications would be able to create or modify EHI through a secure API.

Additional Clarifications to the (g)(10) CCG:

  • The scope of data available in the data responses defined in § 170.315(g)(10)(i) must be supported for searches for multiple patients via the supported search operations finalized in § 170.315(g)(10)(ii).

Supported Search Operations (Multiple Patients)

Regulation text at § 170.315(g)(10)(ii)(B)

(B) Respond to search requests for multiple patients' data consistent with the search criteria included in the implementation specification adopted in § 170.215(a)(4)

Clarifications included in the (g)(10) CCG that apply to paragraph § 170.315(g)(10)(ii)(B)

Technical outcome – Respond to search requests for multiple patients' data consistent with the search criteria included in the implementation specification adopted in § 170.215(a)(4).

Clarifications:

Applies to all applicable base regulatory and SVAP standards:

  • No additional clarifications.

Additional Clarifications to the (g)(10) CCG:

  • The scope of data available in the data responses defined in § 170.315(g)(10)(i) must be supported for searches for multiple patients via the supported search operations finalized in § 170.315(g)(10)(ii).
  • The HL7® FHIR® Bulk Data Access (Flat FHIR®) (v1.0.0: STU 1) implementation specification adopted in § 170.215(a)(4) includes mandatory support for the “group-export” "OperationDefinition."
  • ONC has not included a requirement for Bulk FHIR® import because the standards for these features are still being developed by industry. Applications or systems seeking to import information formatting according to the HL7® FHIR® Bulk Data Access (Flat FHIR®) (V1.0.0:STU 1) can use several methods developed by industry, or can refer to Bulk FHIR® import methods being defined by HL7® at the HL7® FHIR® Bulk Data GitHub page.

Application Registration

Regulation text at § 170.315(g)(10)(iii)

(iii) Application registration. Enable an application to register with the Health IT Module's “authorization server.”

Clarifications included in the (g)(10) CCG that apply to paragraph § 170.315(g)(10)(iii)

Technical outcome – Enable an application to register with the Health IT Module’s “authorization server.”

Clarifications:

Applies to all applicable base regulatory and SVAP standards:

  • Health IT presented for testing and certification must support app registration regardless of the scope of patient search utilized by the application (e.g. single or multiple).
  • This certification criterion requires a health IT developer, as finalized in the Condition of Certification requirements, to demonstrate its registration process, but does not require conformance to a standard.
  • The third-party application registration process that a health IT developer must meet under this criterion is not a form of review or “vetting” for purposes of this criterion.

Applies to base regulatory standard US Core 3.1.1 and SVAP approved standard US Core 4.0.0:

  • For demonstration of the SMART IG "Standalone Launch" steps, health IT developers are permitted to scope US Core IG resources that do not exist in either the standard adopted at § 170.213 (USCDI version 1) or the "Compartment Patient" section of the standard adopted at § 170.215(a)(1) (HL7® FHIR® Release 4.0.1) as either patient/[Resource] or user/[Resource]. These resources include “Encounter,” “Device,” “Location,” “Medication,” “Organization,” “Practitioner,” and “PractitionerRole.” Health IT developers must document their supported scopes according to the technical documentation requirements at § 170.315(g)(10)(viii)(A) and § 170.404(a)(2).

Applies to SVAP approved standard US Core 5.0.1 and USCDI v2:

  • For demonstration of the SMART IG “Standalone Launch” steps, health IT developers are permitted to scope US Core IG resources that do not exist in either the standard adopted at § 170.213 (USCDI version 2) or the “Compartment Patient” section of the standard adopted at § 170.215(a)(1) (HL7® FHIR® Release 4.0.1) as either patient/[Resource] or user/[Resource]. These resources include “Device,” “Location,” “Medication,” “Organization,” “Practitioner,” and “PractitionerRole.” Health IT developers must document their supported scopes according to the technical documentation requirements at § 170.315(g)(10)(viii)(A) and § 170.404(a)(2).

Additional Clarifications to the (g)(10) CCG:

  • ONC expects that apps executed within an implementer’s clinical environment will be registered with an authorization server, but ONC does not require a health IT developer to demonstrate its registration process for these “provider-facing” apps.
  • The requirement that health IT developers must enable an application to register with the § 170.315(g)(10)-certified Health IT Module’s authorization server only applies for the purposes of demonstrating technical conformance to the finalized certification criterion and API Condition and Maintenance of Certification requirements. The practices by all parties (including implementers of Health IT Modules) other than developers of Certified Health IT Modules are not in scope for this certification criterion nor the associated Condition and Maintenance of Certification requirements.
  • Any practices associated with third-party application review or “vetting” by implementers must not violate the information blocking provisions established in the ONC Cures Act Final Rule.

Secure Connection

Regulation text at § 170.315(g)(10)(iv)(A)

(iv) Secure connection. (A) Establish a secure and trusted connection with an application that requests data for patient and user scopes in accordance with the implementation specifications adopted in § 170.215(a)(2) and (3).

Clarifications included in the (g)(10) CCG that apply to paragraph § 170.315(g)(10)(iv)

Technical outcome - (A) Establish a secure and trusted connection with an application that requests data for patient and user scopes in accordance with the implementation specifications adopted in § 170.215(a)(2) and (3). (B) Establish a secure and trusted connection with an application that requests data for system scopes in accordance with the implementation specification adopted in § 170.215(a)(4).

Clarifications:

Applies to all applicable base regulatory and SVAP standards:

First-time Authentication / Authorization for Single Patient Services

Regulation text at § 170.315(g)(10)(V)(A)(1)

(v) Authentication and authorization—(A) Authentication and authorization for patient and user scopes—(1) First time connections—(i) Authentication and authorization must occur during the process of granting access to patient data in accordance with the implementation specification adopted in § 170.215(a)(3) and standard adopted in § 170.215(b). (ii) A Health IT Module's authorization server must issue a refresh token valid for a period of no less than three months to applications capable of storing a client secret. (iii) A Health IT Module's authorization server must issue a refresh token for a period of no less than three months to native applications capable of securing a refresh token.

Clarifications included in the (g)(10) CCG that apply to paragraph § 170.315(g)(10)(v)(A)(1)

Technical outcome – For first time connections, authentication and authorization must occur during the process of granting access to patient data in accordance with the implementation specification adopted in § 170.215(a)(3) and standard adopted in § 170.215(b). Additionally, a Health IT Module's authorization server must issue a refresh token valid for a period of no less than three months to applications capable of storing a client secret. Finally, a Health IT Module's authorization server must issue a refresh token for a period of no less than three months to native applications capable of securing a refresh token.

Clarifications:

Applies to all applicable base regulatory and SVAP standards:

  • Health IT Modules will be explicitly tested for US Core IG operations using authentication and authorization tokens acquired via the process described in the implementation specification adopted in § 170.215(a)(3).
  • Only the relevant parts of the OpenID Connect Core 1.0 including errata set 1 adopted in § 170.215(b) that are also included in the implementation specification adopted in § 170.215(a)(3) will be in-scope for testing and certification.
  • As part of the “permission-patient” “SMART on FHIR® Core Capability” in § 170.215(a)(3), Health IT Modules presented for testing and certification must include the ability for patients to authorize an application to receive their electronic health information (EHI) based on FHIR® resource-level scopes. Specifically, this means patients would need to have the ability to authorize access to their EHI at the individual FHIR® resource level, from one specific FHIR® resource (e.g., “Immunization”) up to all FHIR® resources necessary to implement the standard adopted in § 170.213 and implementation specification adopted in § 170.215(a)(2).
  • Although Health IT Modules presented for testing and certification must include the ability for patients to authorize an application to receive their EHI based on FHIR® resource-level scopes, Health IT Modules are not prohibited from presenting authorization scopes in a more user-friendly format (e.g. grouping resources under categories, renaming the scopes for easier comprehension by the end-user, using more granular scopes), as long as the ability for patients to authorize applications based on resource-level scopes is available, if requested by the patient.
  • Health IT Modules will only be tested for the "Patient Access for Standalone Apps" and "Clinician Access for EHR Launch" "Capability Sets”described in the standard adopted at § 170.215(a)(3).
  • Since the “Patient Access for Standalone Apps” and “Clinician Access for EHR Launch” “Capability Sets” do not include “context-standalone-encounter" ONC will not test Health IT Modules for support for the "context-standalone-encounter" SMART on FHIR® Capability described in the standard adopted at § 170.215(a)(3).
  • Implementers of § 170.315(g)(10)-certified Health IT Modules should be mindful of the information blocking provisions.
  • As part of the requirements at § 170.315(g)(10)(v)(A)(1)(iii), health IT developers must publish the method(s) by which their Health IT Modules support the secure issuance of an initial refresh token to native applications according to the technical documentation requirements at § 170.315(g)(10)(viii) and transparency conditions at § 170.404(a)(2). [see also ONC Clarifications in the Interim Final Rule to Support Native Applications]
  • Application developer affirmations to health IT developers regarding the ability of their applications to secure a refresh token, a client secret, or both, must be treated in a good faith manner consistent with the provisions established in the openness and pro-competitive conditions at § 170.404(a)(4).
  • Health IT developers can determine the method(s) they use to support interactions with native applications and clarify that health IT developers are not required to support all methods third-party application developers seek to use.
  • ONC recognizes there may be some ambiguity in the HL7® SMART Application Launch Framework Implementation Guide (incorporated by reference at § 170.215(a)(3)) in its guidance for supporting native applications, in particular, in providing references to best practices, strategies, and examples such as “OAuth 2.0 for Native Apps: 8.5. Client Authentication”, “OAuth 2.0 Dynamic Client Registration Protocol”, and “universal redirect_uris” without a standardized solution. ONC provides flexibility for how the health IT developer implements the HL7® SMART Application Launch Framework implementation specification, as long as the Certified Health IT Module supports for first time connections the issuance of three-month refresh tokens to native applications capable of securing a refresh token.
  • The paragraph at § 170.215(a)(3) requires health IT developers to support the SMART Application Launch Framework Implementation Guide (SMART IG) “SMART [on FHIR®] Core Capabilities,” including “permission-offline,” which grants support for refresh tokens. The ONC Cures Act Final Rule states, “…Importantly, the implementation specification adopted in § 170.215(a)(3) requires that patients have the ability to explicitly enable the “offline_access” scope during authorization. If the “offline_access” scope is not enabled by patients, patients will be required to re-authenticate and re-authorize an application's access to their EHI after the application's access token expires…” (85 FR 25747). However, the ability of a patient to explicitly enable the “offline_access” scope during authorization is not described in the implementation specification. ONC clarifies that health IT developers must support the ability for patients to be provided information about an application’s request for persistent access prior to the patient sharing their health information, in order to enable patients to make an informed decision during authorization. Examples include, but are not limited to a health IT developer allowing patients to granularly grant “offline-access” scopes during authorization or clearly providing this information as a notice during authorization. The critical requirement is that patients are empowered to deny authorization for offline access.

Applies to base regulatory standard US Core 3.1.1 and SVAP approved standard US Core 4.0.0:

  • Since "Encounter" is not a USCDI v1 data class or data element, ONC will not test Health IT Modules for support for "context-ehr-encounter" SMART on FHIR® Core Capabilities described in the standard adopted at § 170.215(a)(3).

Applies to base regulatory standard SMART App Launch Framework 1.0.0:

  • The “SMART on FHIR® Core Capabilities” in § 170.215(a)(3) are explicitly required for testing and certification because these capabilities are otherwise indicated as optional in the implementation specification.
  • As described in the ONC Cures Act Final Rule, we encourage implementers to adhere to industry best practices to mitigate Cross-Site Request Forgery (CSRF) and other known security threats (85 FR 25742). Proof Key for Code Exchange (PKCE) (Internet Engineering Task Force Request for Comments 7636) is an industry standard that can help mitigate CSRF and other known security threats. The ONC Health IT Certification Program will support the optional use of PKCE during authentication and authorization testing. Health IT developers that implement and require the use of PKCE should include documentation for their PKCE implementation as part of the API Documentation requirement at 45 CFR 170.315(g)(10)(viii) and API Transparency Conditions at 45 CFR 170.404(a)(2).

Applies to SVAP approved standard SMART App Launch Framework 2.0.0:

  • The “capabilities” in AUT-PAT-25 of this criterion’s test procedure are explicitly required for testing and certification because these capabilities are otherwise indicated as optional in the implementation specification.

Additional Clarifications to the (g)(10) CCG:

  • ONC expects implementers of § 170.315(g)(10)-certified Health IT Modules to have the capability of revoking refresh tokens where appropriate.
  • Neither § 170.315(g)(10) nor applicable API Condition and Maintenance of Certification requirements require restricting discretion of implementers (healthcare providers, clinician practices, hospitals, etc.) to set the length of refresh tokens for users of the API including patients and healthcare providers to align with their institutional policies.
  • Implementers of § 170.315(g)(10)-certified Health IT Modules are not prohibited from implementing their § 170.315(g)(10)-certified Health IT Modules in accordance with their organizational security policies and posture, including by instituting policies for reauthentication and re-authorization (e.g., healthcare providers and/or patients could always be required to re-authenticate and re-authorize after a set number of refresh tokens have been issued).
  • Patients are not prohibited from changing the length of refresh tokens to the degree this option is available to them.
  • Implementers of § 170.315(g)(10)-certified Health IT Modules should be mindful of information blocking provisions applicable to them and that requiring patients to reauthenticate and re-authorize at a high frequency could inhibit patient access and implicate information blocking.

Refresh Tokens for Native Applications

As specified in RFC 6749 and the HL7® SMART Application Launch Framework Implementation Guide Release 1.0.0, some native applications are unable to claim they are confidential. By definition, these non-confidential native applications do not have a client_secret to exchange during the client authentication process. However, there are additional methods that non-confidential native applications can use to increase refresh token security during “First time connections.” Methods like Proof Key for Code Exchange (PKCE), the use of application-claimed, private-use Uniform Resource Identifier (URI) schemes as redirect URIs, and utilizing on device secure storage techniques to securely store the refresh token can increase the security of an initial refresh token. Methods like these ensure that an authorization server issues initial access and refresh tokens to the correct corresponding authorized application. The paragraph in § 170.315(g)(10)(v)(A)(1)(iii) requires that Health IT Modules provide support for the issuance of an initial refresh token to native applications capable of securing a refresh token.

OAuth Implementation Presentations

Below is a list of presentations that can be used by Certified Health IT Developers to kick-start their OAuth implementations.

These presentations are best when consumed in the following order:

  1. OAuth2 Overview - Overview of the OAuth2.0 standard and the Authorization Code Grant Type.
  2. SMART App Authorization Overview - Overview of the SMART App Authorization and its value in implementing an interoperable OAuth2 compliant server.
  3. SMART App Client Registration - Information on different concepts and software code for Client Registration.
  4. SMART App Client Authorization Part 1 - Indepth look at the authorization process, the requests and the specification.
  5. SMART App Client Authorization Part 2 - Indepth look at the code used for Client Authorization in Part 1.

Video downloads and PowerPoint slides can be found here: oauth-samples

Subsequent Authentication / Authorization for Single Patient Services

Regulation text at § 170.315(g)(10)(V)(A)(2)

(2) Subsequent connections. (i) Access must be granted to patient data in accordance with the implementation specification adopted in § 170.215(a)(3) without requiring reauthorization and re-authentication when a valid refresh token is supplied by the application. (ii) A Health IT Module's authorization server must issue a refresh token valid for a new period of no less than three months to applications capable of storing a client secret.

Clarifications included in the (g)(10) CCG that apply to paragraph § 170.315(g)(10)(V)(A)(2)

Technical outcome – For subsequent connections, access must be granted to patient data in accordance with the implementation specification adopted in § 170.215(a)(3) without requiring re-authorization and re-authentication when a valid refresh token is supplied by the application. Additionally, a Health IT Module's authorization server must issue a refresh token valid for a new period of no less than three months to applications capable of storing a client secret.

Clarifications:

Applies to all applicable base regulatory and SVAP standards:

  • For subsequent connections of applications capable of storing a client secret, Health IT Modules are required to issue a refresh token valid for a new period of no shorter than three months per the API certification criterion requirement finalized in § 170.315(g)(10)(v)(A)(2)(ii).

Additional Clarifications to the (g)(10) CCG:

  • For subsequent connections, Certified Health IT Modules are not required to issue a new refresh token, but must issue a refresh token valid for a new period of no less than three months. Whether the application receives a “new” refresh token is an implementation decision left to the health IT developer, as long as the “refreshed” refresh token is valid for a new period of no less than three months.

Refresh Tokens and Clients "Capable of Storing a Client Secret"

As specified in RFC 6749 and the HL7® SMART Application Launch Framework Implementation Guide Release 1.0.0, authorization servers send and receive refresh tokens from their clients in two different parts of an OAuth 2.0 flow. First, after resource owner authorization, the authorization server sends an initial refresh token to the client with the initial access token. Second, when an access token has expired and needs to be refreshed, a client exchanges a refresh token for a new access token and optionally another refresh token, which occurs without user authorization. During both exchanges, security is increased (i.e. protecting against leaked refresh tokens) for confidential clients that have a client secret used for client authentication. The (g)(10) criterion paragraphs at § 170.315(g)(10)(v)(A)(1)(ii) and § 170.315(g)(10)(v)(A)(2)(ii) require that clients “capable of storing a client secret” must be given refresh tokens during both of these parts of the OAuth 2.0 flow. Requiring that such clients be given a refresh token valid for a new period of three months during this second part of the OAuth 2.0 flow enables indefinite persistent access without the need for user re-authorization.

Authentication / Authorization for Multiple Patient Services

Regulation text at § 170.315(g)(10)(v)(B)

(B) Authentication and authorization for system scopes. Authentication and authorization must occur during the process of granting an application access to patient data in accordance with the “SMART Backend Services: Authorization Guide” section of the implementation specification adopted in § 170.215(a)(4) and the application must be issued a valid access token.

Clarifications included in the (g)(10) CCG that apply to paragraph § 170.315(g)(10)(v)(B)

Technical outcome – Authentication and authorization must occur during the process of granting an application access to patient data in accordance with the “SMART Backend Services: Authorization Guide” section of the implementation specification adopted in § 170.215(a)(4) and the application must be issued a valid access token.

Clarifications:

Applies to all applicable base regulatory and SVAP standards:

  • Health IT Modules may use access control schemes other than OAuth 2.0 for controlling access to the file server, such as capability URLs. The HL7® FHIR®-I Work Group has documented expectations for the use of capability URLs with the Bulk Data Access IG on the HL7® confluence website. For purposes of Certification testing, Health IT Modules will be tested for the ability to share bulk data files either using OAuth 2.0 bearer tokens or via capability URLs accessible without preconditions or additional steps.
Authentication / Authorization for Multiple Patient Services: Sequence Diagrams

The Bulk Data Export and Authentication/Authorization sequences, according to the §170.315(g)(10) requirements, are described below.

First, according to §170.315(g)(10)(v)(B), Authentication and authorization must occur during the process of granting an application access to patient data in accordance with the “SMART Backend Services: Authorization Guide” section of the Bulk Data implementation guide.

sequenceDiagram
Backend Service->>FHIR Authorization Server: Client Registration (may be out of band)
Backend Service ->> FHIR Resource Server: Discovery request
FHIR Resource Server -->> Backend Service: Discovery response
Backend Service ->> FHIR Authorization Server: Access token request
note over FHIR Authorization Server: On approval
FHIR Authorization Server -->> Backend Service: Access token response
Backend Service->>FHIR Resource Server: Bulk data kick-off request (including access token)
note over FHIR Resource Server: On success
FHIR Resource Server -->> Backend Service: URL of an endpoint for subsequent status requests
Backend Service ->>FHIR Resource Server: Bulk data status request
note over FHIR Resource Server: On export generation completion
FHIR Resource Server -->> Backend Service: Link(s) to the generated bulk data files (output manifest)

Note that generated Bulk Data files may be served by file servers other than a FHIR-specific server.

There are different ways for a client to receive generated Bulk Data files including via Capability URLs for Download Links. The client will refer to the requiresAccessToken field included in the output manifest when retrieving files.

If reqiresAccessToken = true

sequenceDiagram
Backend Service->>File Server: Request files (using access token)
note over File Server: On success
File Server-->>Backend Service: Recieve files

If reqiresAccessToken = false

sequenceDiagram
Backend Service->>File Server: Request files
note over File Server: On success
File Server-->>Backend Service: Recieve files

It is critical that server developers follow the HL7 guidance on Capability URLs for Download Links when choosing to generate output manifests with requiresAccessToken = false.

Patient Authorization Revocation

Regulation text at § 170.315(g)(10)(vi)

(vi) Patient authorization revocation. A Health IT Module's authorization server must be able to revoke an authorized application's access at a patient's direction.

Clarifications included in the (g)(10) CCG that apply to paragraph § 170.315(g)(10)(vi)

Technical outcome – A Health IT Module’s authorization server must be able to revoke an authorized application’s access at a patient’s direction.

Clarifications:

Applies to all applicable base regulatory and SVAP standards:

  • This is a functional requirement to allow health IT developers the ability to implement it in a way that best suits their existing infrastructure and allows for innovative models for authorization revocation to develop.
  • Patients are expected to have the ability to revoke an authorized application’s access to their EHI at any time.
  • For authorization revocation, Health IT Modules presented for certification are permitted to allow short-lived access tokens to expire in lieu of immediate access token revocation. ONC recommends health IT developers limit the lifetime of access tokens to one hour or less as recommended in the standard adopted at § 170.215(a)(3). For purposes of testing and certification, Health IT Modules will be tested for patient authorization revocation occurring within one hour of the request.

Token Introspection

Regulation text at § 170.315(g)(10)(vii)

(vii) Token introspection. A Health IT Module's authorization server must be able to receive and validate tokens it has issued.

Clarifications included in the (g)(10) CCG that apply to paragraph § 170.315(g)(10)(vii)

Technical outcome – A Health IT Module’s authorization server must be able to receive and validate tokens it has issued.

Clarifications:

Applies to all applicable base regulatory and SVAP standards:

  • Although ONC does not specify a standard for token introspection, ONC encourages industry to coalesce around using a common standard, like OAuth 2.0 Token Introspection (RFC 7662), and specifically the profile of the OAuth 2.0 Token Introspection standard included in the SMART App Launch Framework 2.0.0 implementation specification.

Technical API Documentation Content

Regulation text at § 170.315(g)(10)(viii)(A)

(viii) Documentation. (A) The API(s) must include complete accompanying documentation that contains, at a minimum: (1) API syntax, function names, required and optional parameters supported and their data types, return variables and their types/structures, exceptions and exception handling methods and their returns. (2) The software components and configurations that would be necessary for an application to implement in order to be able to successfully interact with the API and process its response(s). (3) All applicable technical requirements and attributes necessary for an application to be registered with a Health IT Module's authorization server.

Clarifications included in the (g)(10) CCG that apply to paragraph § 170.315(g)(10)(viii)(A)

Technical outcome – The API(s) must include complete accompanying documentation that contains, at a minimum: (1) API syntax, function names, required and optional parameters supported and their data types, return variables and their types/structures, exceptions and exception handling methods and their returns; (2) The software components and configurations that would be necessary for an application to implement in order to be able to successfully interact with the API and process its response(s); and (3) All applicable technical requirements and attributes necessary for an application to be registered with a Health IT Module’s authorization server.

Clarifications:

Applies to all applicable base regulatory and SVAP standards:

  • Health IT developers are not required to re-publish documentation from the adopted standards and implementation specifications. However, health IT developers must publish documentation that goes beyond the adopted standards and implementation specifications.
  • Health IT developers are expected to disclose any additional data their § 170.315(g)(10)-certified Health IT Module supports in the context of the adopted standards and implementation specifications.

Technical API Documentation Availability

Regulation text at § 170.315(g)(10)(viii)(B)

(B) The documentation used to meet paragraph (g)(10)(viii)(A) of this section must be available via a publicly accessible hyperlink without any preconditions or additional steps.

Clarifications included in the (g)(10) CCG that apply to paragraph § 170.315(g)(10)(viii)(B)

Technical outcome – The documentation used to meet paragraph (g)(10)(viii)(A) of this section must be available via a publicly accessible hyperlink without any preconditions or additional steps.

Clarifications:

Applies to all applicable base regulatory and SVAP standards:

  • No additional clarifications.

Testing and Certification

Test Procedure

The § 170.315(g)(10) test procedure provides the structure for evaluating conformance of a Health IT Module to the (g)(10) certification criterion requirements.

The ONC Approved SVAP Standards for 2022 include the advancement of four (g)(10) standards (USCDI, US Core, SMART App Launch, and Bulk Data Access). Health IT developers participating in ONC’s Health IT Certification Program can voluntarily incorporate these new versions into their Certified Health IT Modules.

The form below allows for dynamic selection of standards available for (g)(10) certification. Based off the standards selected in the form, a test procedure copy can be viewed by clicking the "View Test Procedure" button. This same test procedure is also contained on healthit.gov.

Select Standards:

US Core:





SMART App Launch:




Bulk Data:




Inferno Framework

The (g)(10) Standardized API Test Kit, built using the Inferno Framework, is used for (g)(10) API testing in the ONC Health IT Certification Program. The (g)(10) Standardized API Test Kit comes with all of the services necessary to test health IT modules seeking to meet the requirements of the Standardized API for patient and population services criterion finalized at § 170.315(g)(10). It is based on the requirements in the ONC Cures Act Final Rule and associated test procedure for § 170.315(g)(10).

Explore Inferno for (g)(10) Testing

Inferno Walkthroughs/Documentation

Get Involved and Ask Questions

  • Join the Inferno Google Group (Google account required, join by clicking "joining the group"). Here you will also find information on the Inferno Monthly Tech Talk meeting which is open to anyone and occurs on the second Wednesday of each month from 1 - 2 PM EST.
  • Join the Inferno Zulip Stream on chat.fhir.org (creating a Zulip account is free). This stream is actively monitored by Inferno's development team.
  • Submit inquiries to ONC via the Health IT Feedback Portal.
  • Submit discovered technical issues on GitHub.

Drummond G10+ FHIR API powered by Touchstone

In July 2022, ONC announced the approval of the Drummond Group’s Drummond G10+ FHIR API powered by Touchstone tool, a new alternative test method (ATM) for testing conformance to ONC’s §170.315(g)(10) Standardized API for patient and population services certification criterion. Through this new ATM, software developers will now have a new option for conformance testing in addition to the previously approved Inferno (g)(10) Standardized API Test Kit. The approval of Drummond’s testing method continues ONC’s mission to further diversify the suite of test methods used as part of the ONC Health IT Certification Program.

Real World Testing Condition and Maintenance of Certification

Health IT developers are required to test the real-world use of APIs.

The § 170.315(g)(10) criterion is included under the Real World Testing Condition and Maintenance of Certification requirements of the ONC Cures Act Final Rule in §170.405, which states:

“A health IT developer with Health IT Module(s) certified to any one or more 2015 Edition certification criteria in § 170.315(b), (c)(1) through (3), (e)(1), (f), (g)(7) through (10), and (h) must successfully test the real world use of those Health IT Module(s) for interoperability (as defined in 42 U.S.C.300jj(9) and § 170.102) in the type of setting in which such Health IT Module(s) would be/is marketed.”

More information can be found on the Real World Testing Fact Sheet and Real World Testing Resource Guide.

Standards Version Advancement Process

Health IT developers are permitted to test and certify using newer versions of implementation guides that have been approved by the ONC National Coordinator.

ONC has established the voluntary Standards Version Advancement Process (SVAP) to enable health IT developers to incorporate newer versions of approved standards and implementation specifications, as part of the Real World Testing Condition and Maintenance of Certification requirements (§ 170.405) of the 21st Century Cures Act.

Using SVAP, Certified Health IT Developers are permitted to voluntarily use a more advanced version of the standard(s) and implementation specification(s) approved by the National Coordinator, than is adopted in the ONC 2015 Edition Certification Criteria. Currently, this flexibility is limited to standards and implementation specifications that are adopted in the certification criteria required to meet the Real World Testing Condition of Certification, which include § 170.315(b), (c)(1) through (c)(3), (e)(1), (f), (g)(7) through (g)(10), and (h). Health IT developers must ensure that they address standards adopted under SVAP in their Real World Testing plans and results submitted to Authorized Certification Bodies. More information can be found on the SVAP landing page.

ONC Buzz Blog: What’s New in the 2022 Approved Standards via Standards Version Advancement Process


  1. HL7®, and FHIR® are the registered trademarks of Health Level Seven International and their use of these trademarks does not constitute an endorsement by HL7


Last update: November 17, 2022