Connect to Payer Endpoints

You can connect to the 1up Payer FHIR R4 endpoints to import clinical data from payers into your patient application.

Step 1 — User Authorization to Receive a Code

To connect to the 1up authorization server, your application uses a stand_alone launch and connects to the https://auth.{base-url}/oauth2/authorize/{system-id} endpoint.

When you connect to the endpoint, make sure to replace the base_url and system-id values with the correct values for the Health Plan. For example, for the 1up Demo Health Plan, the base_url is 1updemohealthplan.com and the system-id is demoplan.

You will receive an email with information about the /authorize endpoints for the authorized Health Plan endpoints.

When you connect to the endpoint, you must include the following query parameters.

Query Parameter

Description
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 that you registered with your application.

You can’t use a localhost redirect with our Production environments. You can only use localhost in the 1up Sandbox for testing initial development.
scope

You can specify these scopes in the query parameter:

patient/*.read (default)

user/*.read

launch/patient

openid

For more information about Scopes, see Scopes and Launch Context.
state

This parameter is not required but it is recommended that you use it to confirm the validity of a session.

If you pass a state with the request, the authorization server returns it as a query string parameter when redirecting to your application.

For more information about the state parameter, see state in RFC6819.

The following is an example request to the 1up Demo Health Plan endpoint. 

https://auth.1updemohealthplan.com/oauth2/authorize/demoplan?client_id={your_app_client_id}&scope=user/*.read&state={state}&redirect_uri={your_app_redirect_uri}

Make sure you replace the {placeholder text} with the correct values for your application.

After you submit the request to the endpoint and the authorization page appears, you must verify your identity. The authorization mechanism that you use depends on the Health Plan you’re connecting to. For example, member portal credentials (user name and password), email-based authentication, or multi-factor authentication (MFA).

At the end of the authorize process, you’re sent to the redirect_uri you registered with your application client ID, which includes the OAuth 2.0 authorization code returned as a query parameter.

Step 2 — Exchange Your Code for a Token

You’ll use the authorization code from the response to your authorization request to exchange for an OAuth 2.0 access token using the 1up https://auth.{base-url}.com/oauth2/token endpoint.

You can use the following example request to get your token.

Make sure to replace the {placeholder text} in the example with your token.

Submit the following request.

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 Your Token

After you get your access_token in Step 2, you can use that token to query the FHIR resources that you have the scopes and permissions to access (read-only).

To query FHIR resources, submit the following request. 

curl --location --request GET 'https://api.{base-url}/r4/Patient/{patient_id}' \
--header 'Authorization: Bearer {access_token}'

Make sure to replace the {placeholder text} in the example with your token.

After you submit the request with your access token, the following resources are available:

  • ExplanationOfBenefit

  • Coverage

  • Patient

  • Organization

  • Practitioner

A few health plans also have a subset of Clinical Resources available for some patients. This can include resources such as AllergyIntolerance and MedicationRequest.