Patient Access API Specification

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

The user to whom the FHIR resource belongs.

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

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.

The FHIR Server that contains the FHIR resources.

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

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

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

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.

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.

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

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

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

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

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.

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.

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.

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.