SMART On FHIR® App Connection

This guide will help you through the steps of connecting your SMART on FHIR application to 1upHealth. This guide will cover the process of creating an application with 1upHealth and how to use OAuth with the 1upHealth Authorization Server.

Step 1: Create an Account in Sandbox

  1. Create An Account in our sandbox Developer portal, by clicking "Don't have an account? sign up"

  2. Once you have created an account, log into our sandbox Developer portal, and click "ADD YOUR FIRST APPLICATION". Important: When you create the account, you will be asked to enter your redirect_uri. Make sure that you get this correct or you will need to create a new application (you can not edit the redirect_uri directly in the developer console). Also note down the client_id and secret.

Step 2: Metadata Endpoint

To determine which authorize and token endpoints to use, you should make a GET request to the metadata endpoint:

curl -X GET 'https://api.1uphealthdev.com/r4/metadata' \
--header 'Accept: application/json'

The current options for fhir_version are: dstu2, stu3 and r4.

Step 3: Your Application Requests A Code

Your application will use a stand_alone launch and directly hit our authorization server at https://authv2.1uphealthdev.com/connect/testplan. When you hit this endpoint, you will need to include the following query string parameters.

  • response_type: This must contain the value code.

  • client_id: This must contain the client_id of the application you previously registered in the 1upHealth developer console.

  • redirect_uri: This must contain the redirect_uri you registered with your application.

  • scope: You will need to specific user/*.read, launch/patient, and openid . We will be adding support for patient/*.read in the future, but for now please use these scopes.

  • state: If you choose to pass a state with the request, the authorization server will simply return it as a querystring parameter when redirecting to your application. This parameter is not required but it is recommended that it is used to confirm the validity of a session. See more here.

Here is a sample request with variables that you need to fill in:

https://authv2.1uphealthdev.com/connect/testplan?client_id={your_app_client_id}&scope=user/*.read%20launch/patient%20openid&state={state}&redirect_uri={your_app_redirect_uri}

When you arrive at the authorization page, you will need to enter the username and password for a user. We recommend you use one of our test users that is already populated with synthetic r4 data (1 patient resource, 3 ExplanationOfBenefit, 2 Coverage, 3 MedicationStatement resources):

username: 1up
password: iscool

Step 4: Exchange Code for Token

You will receive an authorization code in the response from Step 3 which you can exchange for an OAuth 2 access token using our https://authv2.1uphealthdev.com/oauth2/token endpoint. Here is a sample request where you will need to fill in your app details:

curl --location --request POST 'https://authv2.1uphealthdev.com/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={your_client_id}' \
--data-urlencode 'client_secret={your_client_secret}' \
--data-urlencode 'code={code_received_step_3}' \
--data-urlencode 'grant_type=authorization_code'

For more information on SMART on FHIR please visit: http://www.hl7.org/fhir/smart-app-launch/

Step 5: Query FHIR Resources Using Token

After receiving an access_token in Step 4, you can now use that Token to query FHIR resources you have the scopes and permissions to access (read-only).

curl --location --request GET 'https://api.1uphealthdev.com/r4/Patient/{patient_id}' \
--header 'Authorization: Bearer {access_token_from_step_4}'

Unsupported Features

patient/*.read: Work in progres

user management api: This authorization flow does not support users created using this api because they do not have a username or password that is hosted by 1upHealth.

client_id and client_secret auth: We do not support this authorization flow currently but we will be rolling out its support in the future.

Questions or problems?

Reach out to us [email protected]