Skip to main content

Patient Access API Specification

Patient Access API Overview

Welcome to our Patient Access API, designed in compliance with the CMS 9115-F regulations. This API facilitates secure and efficient access to patient data, utilizing the HL7® FHIR® R4 standard, a globally recognized framework for health care information exchange.

What is an API?

API stands for “Application Programming Interface” and is a way for an application such as a SMART on FHIR application to interact with a server on the internet. The Patient Access API allows an application, with the member's permission, to access the member's health data. This access allows the application to give a member the ability to view their health data, download a copy of the data, or share the data with other organizations.

Connecting Your Application

To connect your application to the Patient Access API, you will need to ensure that your application supports the following standards:

Authentication and Authorization

To secure access to patient (member) data our API employs robust OAuth 2.0 protocols for authentication and authorization. Client applications must already be registered, at which time they receive unique credentials.

To secure access:

  1. Obtain Access Tokens — Send a request to our authentication endpoint to receive an access token.

  2. Scopes and Permissions — Access tokens define the scope and level of access, ensuring that applications only access the necessary data.

The Patient Access API makes the member's coverage, explanation of benefits, and all available clinical data available for access by members and their delegates. An API “user” (either the member or their delegate/proxy) accesses their data by using a third-party (client) application that is designed to retrieve and display available information from the Patient Access API. Third-party applications must be given authorization by the user to access the data on the user's behalf. The authentication and authorization mechanism for granting such access to applications is the OAuth 2.0 Authorization Code workflow. The Authorization Code workflow ensures that access is authorized and restricted appropriately as per the regulations governing the Patient Access API.

The following sections provide an overview of the OAuth 2.0 architecture and implementation for the Patient Access API.

Definition of Terms

Resource

A unit of information available in the API — specifically a FHIR resource.

Resource Owner

The user to whom the FHIR resource belongs.

User

A member, or their delegate/proxy, to whom the data belongs and who is responsible for authorizing access to the data.

Delegate/Proxy

A person who has been granted rights to a member's records on the member's behalf. This is commonly the parent or guardian of a child or the adult child of an elderly person, but the rights to authorize access to records may be granted to any person the member chooses.

Resource Server

The FHIR Server that contains the FHIR resources.

Client or Third-Party App

An application, usually mobile or web, that is designed to retrieve FHIR resources from the Resource Server and display them to the user.

Authorization Server

The server that maintains user credentials and where the user logs in to authorize access to the API. The Authorization Server issues authorization codes and tokens to the client applications. The Authorization Server is also known as the “Issuer”.

Authorization Code

A code that is issued to a client app by the Authorization Server once a user has successfully authorized access for the client app.

Access Token (OIDC)

An OAuth 2.0 token issued by the Authorization Server. The access token is an OpenID Connect (OIDC) token containing member information and authorized scopes. Access tokens are short lived, providing access for a small window of time, such as 30 minutes, before expiring.

Refresh Token

An OAuth 2.0 token issued by the Authorization Server which may be used to acquire a new access token on behalf of the user without requiring the user to re-authenticate. Refresh tokens are long lived, allowing the application to continue provided user access without frequent authentication requests.

Client ID/Secret

A client ID is issued to each third-party app and uniquely identifies the app to the Authorization Server. The client Secret is a confidential value which enables the client to authenticate itself as a valid client to the Authorization Server.

Claims

Claims are key/value pairs specified in the Access Token to encode information about the Authorization Server, user, and other authorization details. For example, the “iss”claim indicates the “issuer” and the “exp” claim indicates the “Expiration time” of the token.

Scopes

Scopes are a claim within the Access Token, and consist of a space delimited list of text strings indicating precisely what the user has authorized the application to access on the user's behalf. The standard set of scopes includes things like contact information and user information, however for the Patient Access API, a set of scopes describing FHIR resource types and sensitive data types are included in the authorization code workflow. Scopes are encoded into the Access Token to indicate authorization to access the related data.

Specifications and Standards

The OAuth 2.0 workflow implemented for the patient access API adheres to the following specifications and standards:

OAuth 2.0

The OAuth 2.0 specification describes the authorization code workflow, as well as several other workflows not utilized by the patient access API. https://www.rfc-editor.org/rfc/rfc6749.htmlOpens in a new tab

SMART on FHIR

The SMART on FHIR Implementation Guide describes the “SMART App Launch Framework” which specifies how a third-party application should initiate authorization and access to FHIR resources. For the Patient Access API, the specific use case that is implemented is “Patient apps that launch standalone.” http://www.hl7.org/fhir/smart-app-launch/Opens in a new tab

OpenID Connect (OIDC)

OIDC is an identity layer on top of the OAuth 2.0 protocol which specifies how to encode information about the user and the relevant claims and authorizations the user has made into the Access Token itself. https://openid.net/specs/openid-connect-core-1_0.htmlOpens in a new tab

Actors and Configuration

The following actors and configurations enable the OAuth Authorization Code workflow for authorizing access to the Patient Access API:

generated description: actors.jpg

Resource Owner

The resource owner is the member or proxy that the user has delegated authorization permissions to. The user registers an account with client organization and is issued username and password credentials. The user employs the client application to interact with the Patient Access API.

Client

The client application is the third-party application, typically a mobile application or web site. The client applications that will utilize the Patient Access API will be apps designed to access EOB and clinical information on behalf of the user/member. The apps will be designed to utilize the API metadata and SMART on FHIR configuration file to discover the Authorization Server and initiate the Authorization Code workflow. All client apps must be issued a client ID and Secret by the Authorization Server prior to initiating access to the API.

Authorization Server

The Authorization Server is an OAuth 2.0 Server. It is configured for customization of scopes, and the inclusion of the patient MPIID into the Access Token as required by SMART on FHIR.

Resource Server

The Resource Server is the system that implements the required FHIR Implementation Guides and serves up the coverage, EOB, and clinical information.

The Resource Server validates the Access Token and enforces the scopes that are specified in the token. The Resource Server compares the authorized scopes against the data that is being requested from the API and either allows or disallows the retrieval of the data accordingly.

Patient Identifier API

The OAuth Server is responsible for authorizing members and generating Access Tokens. The OAuth Server includes the patient identifier when responding to client applications. You will need a value for each of the settings below. You should receive these values when you register your application.

Setting Value Received When You Registered Your Application
API Endpoint  
OAuth Issuer  
Client Name  
Client ID  
OIDC aud  

Endpoints and Operations

The API provides a range of endpoints tailored to various data retrieval needs.

Implementation Guides

The Patient Access API FHIR endpoint is configured using the following implementation guides:

Profiles and Resources
Profile Resource
C4BB CoverageOpens in a new tab Coverage
C4BB ExplanationOfBenefit Inpatient InstitutionalOpens in a new tab ExplanationOfBenefit
C4BB ExplanationOfBenefit PharmacyOpens in a new tab ExplanationOfBenefit
C4BB ExplanationOfBenefit Professional NonClinicianOpens in a new tab ExplanationOfBenefit
C4BB OrganizationOpens in a new tab Organization
C4BB PatientOpens in a new tab Patient
C4BB PractitionerOpens in a new tab Practitioner
US Core AllergyIntolleranceOpens in a new tab AllergyIntollerance
US Core ConditionOpens in a new tab Condition
US Core DiagnosticReport-LabOpens in a new tab DiagnosticReport
US Core DiagnosticReport-NoteOpens in a new tab DiagnosticReport
US Core DocumentReferenceOpens in a new tab DocumentReference
US Core EncounterOpens in a new tab Encounter
US Core ImmunizationOpens in a new tab Immunization
US Core ImplantableDeviceOpens in a new tab Device
US Core ObservationLabOpens in a new tab Observation
US Core LocationOpens in a new tab Location
US Core MedicationOpens in a new tab Medication
FHIR R4 MedicationDispenseOpens in a new tab MedicationDispense
US Core PractitionerRoleOpens in a new tab PractitionerRole
US Core ProcedureOpens in a new tab Procedure
FHIR R4 MedicationStatementOpens in a new tab MedicationStatment
FHIR R4 Observation VitalSignsOpens in a new tab Observation
FeedbackOpens in a new tab