Comment on page

Connecting to Payer Endpoints

Information on how to connect the Payer FHIR R4 endpoints to bring data into your patient app

Step 1: User Authorization to receive a code

Your application will use a stand_alone launch and directly hit our authorization server https://auth.{base-url}/oauth2/authorize/{system-id} endpoint. The base url and system ID will differ based on each health plan (e.g., our Demo Health Plan is and demoplan). As systems come live you will receive the authorize endpoints for health plans via email.
When you hit this endpoint, you will need to include the following query parameters.
  • 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. Note - you may not use a localhost redirect with our PROD environments, but can in our sandbox while testing and developing.
  • scope: The default scope will be user/*.readu. However you will also be able to specify in the query parameter these additional scopes:patient/*.read, launch/patient, and openid . See more information on scopes here.
  • state: If you choose to pass a state with the request, the authorization server will simply return it as a query string 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 to our Demo Health Plan endpoint with variables that you need to fill in:{your_app_client_id}&scope=user/*.read&state={state}&redirect_uri={your_app_redirect_uri}
When you arrive at the authorization page the user will need to verify their identity through one of several mechanisms determined by the specific health plan such as member portal credentials (username and password), email-based, MFA, etc.
At the end of the authorize process the user will will be sent back to the redirect_uri you registered with your application client ID, and will include the OAuth 2.0 auth code passed back as a query parameter

Step 2: Exchange Code for Token

You will receive an authorization code in the response from above which you can exchange for an OAuth 2 access token using our https://auth.{base-url}.com/oauth2/token endpoint. Here is a sample request where you will need to fill in your app details:
curl --location --request POST 'https://auth.{base-url}/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'

Step 3: Query FHIR Resources Using Token

After receiving an access_token in Step 2, 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.{base-url}/r4/Patient/{patient_id}' \
--header 'Authorization: Bearer {access_token_from_above}'
The following resources will typically be available:
  • ExplanationOfBenefit
  • Coverage
  • Patient
  • Organization
  • Practitioner
  • Subset of Clinical Resources available (e.g. AllergyIntolerance, MedicationRequest, etc.)
Resources will adhere to the following FHIR Implementation Guides: