Patient Access API

The Patient Access API enables individual patients to access their healthcare data through the healthcare app of their choice. This API provides payer-maintained USCDI data via US Core resources, including clinical data, claims and encounter information, and information about prior authorizations. Data is available for dates of service on/after Jan 1, 2016. For more information on the Patient Access API requirements, see the CMS Interoperability and Prior Authorization Final Rule (CMS-0057-F).

Overview

Data feeds into Orchestrate Server from the connected EHR/payer/provider system. Orchestrate converts, consolidates, and uplifts the data before making it available to downstream APIs, including the Patient Access API.

The patient’s healthcare app of choice (“Patient App”) can connect to the Patient Access API in accordance with the FHIR standard. The general sequence of events is:

• Query the Capability Statement to determine supported operations and authentication endpoints.
• Perform OAuth exchange with the authentication endpoints to authorize user access.
• Utilize FHIR operations to access health data resources.

Capability Statement

The Patient Access API provides a Capability Statement at [base endpoint]/metadata specifying the available resources, authentication endpoints, and more. See the programming guide for details.

User Authorization

When a patient app wishes to utilize the API, it asks Orchestrate Server for authorization to access certain FHIR resources. This process uses FHIR’s SMART App Launch framework to ensure that the app only receives data that the user has consented to share with the app. Once authenticated, Orchestrate will issue OpenID Connect access/ID/refresh tokens to the app, which it can use to access FHIR resources.

Orchestrate Server relies on external OpenID identity providers (such as Microsoft’s Entra or Okta) to verify the user’s identity. See Identity Providers for more information.

The full exchange between Orchestrate and the identity provider is illustrated in the sequence diagram below. In general, the steps are:

1. Patient App requests an authorization code (using the authorize endpoint).
2. Orchestrate mediates the exchange between the Identity Provider and user to:
   • Confirm the user’s identity.
   • Determine which FHIR patient(s) the user has access to.
   • Establish that the user has consented to share data with the Patient App.
3. If authorized, Orchestrate returns an authorization code to the Patient App.
4. Patient App uses the authorization code to request an access token and refresh token (using the token endpoint).
5. Patient App provides the access token when requesting FHIR resources.

Both the authorize and token endpoints can be discovered via the Capability Statement. For more details on how Orchestrate connects to an identity provider see Identity Providers.

Access Tokens

Once you have obtained the access token using the process above, it should be included in the request’s HTTP header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Scopes

When requesting an authorization code, the patient app will provide a list of scopes reflecting the permissions being requested. See SMART on FHIR Scopes for details about what scopes are available and how they are used.

Delegated (Family) Access

If a user is associated with multiple FHIR patients (such as themselves and their dependent children), Orchestrate can allow access to healthcare data from associated accounts. To enable this feature, Orchestrate Server requires additional information from the identity provider to know which FHIR Patient IDs the user can access. See Identity Providers for more information.

Client Security

Orchestrate Server has several security mechanisms available to ensure that only authorized patient apps (clients) are allowed to request resource access. See Identity Providers for more information.

Refresh Tokens

In addition to the access token, the patient app will also receive a refresh token. When the original token expires, the refresh token can be used to request a new access token without making the user log in again. See the SMART App Launch documentation for more information. If the identity provider has revoked the user’s access, Orchestrate will reject the refresh token request.

If the user is associated with multiple family members, their access is updated as part of obtaining a new access token.

Accessing Resources

All FHIR requests are based on resources. See the Programming Guide for details.