FHIR

Description

The API resources detailed below are designed to satisfy the United States Core Data for Interoperability (USCDI) requirements set forth by the Office of the National Coordinator (ONC).

AuroraEHR's APIs are based on the HL7 FHIR® US Core Implementation Guide STU3 Release 3.1.1 and HL7 FHIR Release 4 standards standards.

Terms of Use

Users and/or developers must agree to the Terms of Use prior to utilizing these APIs.

Service Base URLs

This section is required for ONC 2015 certification. The 'Production Endpoints' will list the FHIR Base URLs (ie. service base URLs) of the AuroraEHR installations that are utilizing the ONC 2015 certification. Please note that Production and Testing endpoints are subject to change.

Testing Endpoints

•FHIR:   https://sandbox.pai.healthcare/preview/fhir

•OAuth: https://sandbox.pai.healthcare/preview/fhir/oauth/

Production Endpoints

•There are currently no production endpoints

Software Requirements

In order to access AuroraEHR API, a REST client such as Postman or cURL, or a programming language (Java, Python, etc) that can be used to make HTTP requests, is needed.

Configuration Requirements

API integration is contingent upon the following configuration settings:

•Application must read and parse JSON responses. XML is not supported.

•Application must assure that sensitive data elements are transmitted only to authenticated servers, over a TLS secure channel. Connection must utilize TLS version 1.2 or higher.

Registration

Anyone interested in obtaining access to AuroraEHR APIs must go through the registration process:

1.Send an email containing the following details to gvti@practice-alt.com.

API Access Request:
Name/Organization:                                

Email Address:                                        

Phone Number:                                        

Purpose of API access:                                

2.Practice Alternatives Inc. will then review the request and, if approved, provide an OAuth client identifier for use with the authorization server.

Authorization

Practice Alternative Inc.’s API implementation uses SMART Application Launch 1.0.0, OAuth 2.0 and Bulk Data 1.0.1 framework as methods through which an app requests authorization to access a FHIR resource, and then uses that authorization to retrieve the resource. All API requests are authenticated by passing a bearer token in the authorization header. This token can be obtained via your PAI provided credentials.

Authorization can take place in two different ways. The chosen method of authorization will depend on the needs and capabilities of the 3rd-party client.

#1: authorization_code grant_type

This method is generally used when a user/person is able to authenticate themselves using a supplied username and password combination. The user is presented with a login screen where they will also indicate which FHIR scopes they are authorizing the SMARTonFHIR application to access. Upon successful log in, an access token and refresh token will be issued. The access token must be used for all queries to AuroraEHR's FHIR server.

The call to the /authorize endpoint is an HTTP GET, where the parameters are supplied as the query string.

The parameters to use in the call to the /authorize endpoint:

For example:

https://dev.pai.healthcare/preview/fhir/oauth/authorize?response_type=code&client_id=sdfb235LKJL5UOIR&code_challenge=s09df7987234&code_challenge_method=S256&audience=https://dev.pai.healthcare/preview/fhir&redirect_uri=https://smartfhirapp.com&scope=patient/Patient.read patient/Condition.read&state=ds89f798234

A successful authorization will return an HTTP 302 where the Location is the redirect_uri with a code parameter as part of the query string.

The call to the /token endpoint is an HTTP POST, where the parameters are supplied in the body of the request. The request's Content-Type must be application/x-www-form-urlencoded

The parameters to use in the call to the /token endpoint:

For example:        client_id=sdfb235LKJL5UOIR&client_secret=8f09s8f0098as0d8f234kjl2k3j4l2lk5j&code=d908s7f98s7f929834439868dlkfgjlkdfjg&code_verifier=KSLDFJ209384lkjlskdf&audience=https://dev.pai.healthcare/preview/fhir&grant_type=authorization_code&scope=patient/Patient.read patient/Condition&redirect_uri=https://smartfhirapp.com

A successful response will return an HTTP 200 where the body of the response will contain an access_token.

#2a: client_credentials grant type (capable of securely storing client secret)

This method is generally used when there is no user to provide authentication. This could be for a back-end server running batch requests, a one-time export, etc. A call is made to the /token endpoint only and the client_id and client_secret are supplied in the request. A successful call to the /token endpoint will result in an access token being issued. The access token must be used for all queries to AuroraEHR's FHIR server.

The call to the /token endpoint is an HTTP POST, where the parameters are supplied in the body of the request. The request's Content-Type must be application/x-www-form-urlencoded

The parameters to use in the call to the /token endpoint:

For example:

grant_type=client_credentials&client_id=sdfb235LKJL5UOIR&client_secret=8f09s8f0098as0d8f234kjl2k3j4l2lk5j&audience=https://dev.pai.healthcare/preview/fhir

#2b: client_credentials grant type (not capable of securely storing client secret)

This method is similar to the method described immediately before. However, if the client_secret cannot be securely stored, then the client is responsible for issuing a JWT containing the client_id. The supplied JWT must be encrypted using an RS384 async encryption key. The public key must be publicly available and the URL must be supplied to PAI during the registration process. AuroraEHR's FHIR server will then supply the client_secret when issuing an access token. The access token must be used for all queries to AuroraEHR's FHIR server.

Three application/x-www-form-urlencoded parameters are required: grant_type, client_assertion_type, and client_assertion. The grant_type parameter must be set to client_credentials. The client_assertion_type parameter must be set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer. The client_assertion parameter must be set to a JWT containing the following claims: iss - the client_id, sub - the client_id, aud - the token endpoint, jti - the JWT ID, exp - the expiration time, and iat - the issuance time. The JWT's header needs to be valid and contain a kid claim that was provided to PAI during the registration phase.

Assuming everything checks out, a response similar to the Login Flow for machines/servers/batch scripts (capable of securely storing client secret) containing the access token will be issued.

Proof Key for Code Exchange

PKCE is supported as per IETF RFC 7636 , and may be required on a per-client basis.

PKCE is a way to mitigate Cross-Site Request Forgery (CSRF) and authorization code injection attacks. This is done by generating an RS256 code_challenge and code_verifier. These are then supplied at different times during the authorization/authentication process. During the call to the /authorize endpoint, the code_challenge parameter is supplied as part of the query string. Then, during the subsequent call to the /token endpoint, the code_verifier parameter is supplied as part of the HTTP Post request body. If the code_challenge is not the expected value, based on the code_verifier, no token will be returned.

The value of the code_verifier is 32 random bytes that are base64 encoded. The code_challenge is a SHA256 hash of the code_verifier. Since the code_verifier is sent in the /authorize endpoint call, and the code_challenge is sent in the /token endpoint call, both the code_verifier and code_challenge need to be generated before the call to the /authorize endpoint is made.

Errors and Response Codes

AuroraEHR APIs use the standard HTTP response codes to indicate success or failure of an API request. Any exceptions will return the most relevant code and response listed below.