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 the 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 query, add, and update health data resources.

These steps are described in detail in the following sections.

Capability Statement

When the patient app first begins using the Patient Access API, it will query for the API’s Capability Statement. The capability statement includes:

• FHIR interface version.
• Authentication endpoints.
• Supported resources, search fields, and operations.

The URL for the capability statement is:

[base endpoint]/metadata

For example: https://yourorchestrateserver.careevolution.com/api/fhir/r4/metadata

Returns:

{
    "resourceType": "CapabilityStatement",
    "status": "active",
    "date": "2025-10-08T14:15:20.72644+00:00",
    "publisher": "CareEvolution",
    "software": {
        "name": "Orchestrate Server",
        "version": "1.0.0"
    },
    "fhirVersion": "4.0.1",
    ...
    "rest": [
      "security": { ... }  // Info on authorization endpoints
      "resources": { ... } // Info on available resources
    ]
}

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.

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.

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.

Client Security

Identity provider integration supports the following methods of client authentication for security:

• Client Secret
• Client Assertion (public key)

In addition, Orchestrate supports PKCE to prevent CSRF and code injection attacks.

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, the 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.

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 - modular health data components. For example, a Patient is a resource, as is a Medication. Resources stand on their own, but may have relationships with each other. An Encounter may relate back to a particular Patient and involve several Observations.

Resource URLs

Basic interactions are performed by issuing a HTTP request to the appropriate resource URL. Some sample requests are shown below. For complete details, see the HL7 FHIR Specification.

Access Tokens

Every request must include an access token granting you access to the resource. This token should be included in the request’s HTTP header:

Authorization: Bearer YOUR_ACCESS_TOKEN

See Authorization for details on obtaining an access token.

Available Operations

The Capability Statement provides a complete list of available resources, search fields, and available operations. For example, within the Capability Statement, you can see that the Patient resource allows searching by ID and has an export operation, among other things.

{
    "type": "Patient",
    ...
    "searchParam": [
      {
        "name": "_id",
        "definition": "http://hl7.org/fhir/SearchParameter/Resource-id",
        "type": "token",
        "documentation": "Resource id"
      },
      ...
    ],
    "operation": [
      {
        "name": "export",
        "definition": "http://rosetta.careevolution.com/FHIR/OperationDefinition/Patient-export"
      },
      ...
    ]
  },
  ...
}