FHIR API HIEBus™ FHIR API
Interface Guide

Getting an Access Token

The FHIR Interface protects health data (PHI) by requiring authentication on all operations. It supports SMART® Authorization (also known as “SMART on FHIR”), a common authentication scheme built on the OAuth2 standard. With the exception of the conformance information, every request must contain an access token for authorization.

HIEBus Clients

HIEBus will only issue access tokens to registered applications. You will need a client ID provided by your site administrator to request an access token.

User Permissions

An access token is associated with a specific user, and only grants permission to resources that the user would have access to in the HIEBus web client.

For example, a patient user would typically only see their own patient data. A clinician would only be able able to access information for patients they were authorized to view.

Finding the OAuth Endpoints

The OAuth server information is included in the conformance statement. It is recommended that you look up the OAuth endpoints rather than coding them directly into your application. See the Simple Query Example for some sample code showing how you can read the OAuth endpoints from the conformance statement.

OAuth Urls
OAuth Urls

Getting an Access Token

HIEBus supports standard OAuth2 authorization flows, including FHIR’s SMART® App Launch Framework. Two sample flows are described below. Consult the SMART App or OAuth documentation for more details and other flows.

Password Credentials Grant

The Resource Owner Password Credentials grant is the simplest OAuth exchange. It is also the least secure, because it requires the client app to directly handle the user’s username and password.

With this flow, the user enters their username and password on the client, and those credentials are sent directly in the authorization request to the server. If successful, the server responds with an authorization code, which the client can trade for an access token. This is illustrated below:

Password Credentials Grant
Password Credentials Grant

See the Simple Query Example for an example using Password Credentials Grant.

Authorization Code Grant

The Authorization Code grant is optimized for client-server exchanges. With the addition of a Proof Key for Code Exchange (PKCE), it is also well-suited for native/mobile apps. This is the recommended authorization flow for applications using the FHIR Interface.

With this flow, the client sends an authorization request to the server. The server prompts the user to log in securely (typically using the device’s web browser) and authorize the user. If successful, the server then redirects the user back to the original application with an authorization code. The client can use that authorization code to request an access token.

Authorization Code Grant
Authorization Code Grant

Proof Key for Code Exchange (PKCE)

PKCE guards against your authorization code from being hijacked by a malicious application on the same device. To use PKCE, you simply add an extra verification code to the authorization request and token request, and the server verifies that the codes match.

Many OAuth libraries will support PKCE transparently. If your library does not, or if you want more information about using PKCE, there’s a great guide on oauth.com.

Redirect URI on Native/Mobile Apps

Unlike web apps, native/mobile apps do not inherently support the redirect URI needed by the Authorization Code grant. It is necessary to register the app with the device’s operating system so that the redirect can get the user back to your app. You can use Universal Links in iOS or App Links in Android to accomplish this.