AmeriHealth Caritas Developer Portal CMS Interoperability Additional Documentation

CMS Federal Mandate Information

The Interoperability and Patient Access final rule (CMS-9115-F) is focused on driving interoperability and patient access to health information by liberating patient data using CMS authority to regulate Medicare Advantage (MA), Medicaid, CHIP, and Qualified Health Plan (QHP) issuers on the Federally-facilitated Exchanges (FFEs).

CARIN Code of Conduct

A foundational set of principles for how health care organizations can share data with consumer applications.

Let's begin

The AmeriHealth Caritas (AH) Developer portal provides access to the AmeriHealth Caritas implementation of the CMS Interoperability FHIR APIs, which are based on the Health Level 7® (HL7) Fast Healthcare Interoperability Resources (FHIR®) 4.0.1 standards AmeriHealth Caritas provides three APIs: Patient Access, Provider Directory, and Formulary. The following sections detail how to register an application in the AmeriHealth Caritas Developer portal and how to connect such applications to the FHIR server.

Quick Start

To begin, you'll need to create your account, register your application, and get your application authorized via a Client ID and Client Secret. Let's begin:
  1. Create Developer Account
    1. Select Register Now and follow the prompts to register your account.
  2. Activate Developer Account
    1. After registration, you will receive an email to activate the account. Click the link within the email to activate the account.
  3. Login to Developer Account
    1. Once your account is activated, it's time to start registering your application(s).
    2. Login to get started.
  4. Register Application
    1. Create/register your application; select Applications > Register Application
    2. Name your application and input the applicable details
    3. Provide the callback URLs (separated by comma) for the application
    4. Review attestation page and edit the registration information as necessary
    5. Once everything is correct, press the Submit button.
      6. Note: Your submitted request will reviewed and approved. Once approved, you will recieve an approval email that will instruct you to log into AmeriHealth Caritas Developer Portal in continue the process. Once logged in, you will see a Refresh button enabled. Upon selecting the Refresh button, you will be given a Client ID and a Client Secret for your registration application. This information will be shown in your registered applications list.
  5. Use AmeriHealth Caritas APIs
    1. Once successfully registered, you can begin using the APIs.
    2. Begin using AmeriHealth Caritas APIs with your newly registered application
      3. Note: Registered users can access the Sandbox version of patient credentials.

How to Connect

Follow these steps to use your application's Client ID, Client Secret, authorization codes, and tokens to securely connect your application to the Patient Access API.

Authorization Overview

Based on the FHIR SMART app framework, the Patient Access API relies on OAuth 2.0 specifications and OpenID Connect Core 1.0 standards to establish secure connections the AmeriHealth Caritas FHIR server supports both the standard OAuth 2.0 and OIDC web application authorization flow, and the Proof Key for Code Exchange (PKCE) authorization flow.

  1. When using the Patient Access portion of AmeriHealth Caritas APIs ONLY
    1. You will need to utilize security protocols to connect to the AmeriHealth Caritas FHIR end point.
  2. When using the Provider Directory API OR Formulary API
    1. You don't need to implement the security protocols.

Application Registration

  1. Create Developer Account and Register Application
    1. Once registered, you will need to have a callback URL (aka redirect URI) to assign to your application, which will be used during the authorization flow.
    2. After registration, you will be assigned a Client ID and Client Secret.
Currently, the following scopes are available and enabled by default:
Scope Grants
patient/*.read Permission to read resources for the current patient
openid fhirUser Permission to retrieve information about the current logged-in user.
launch/patient When launching outside the EHR, ask for a patient to be selected at launch time.
offline_access Request a refresh_token that can be used to obtain a new access token to replace an expired one, even after the end-user no longer is online after the access token expires.
  1. Store Client Secret in a Safe Location
    1. The Client Secret should only be used if it can be kept confidential, such as communication between your server and the AmeriHealth Caritas API.
      2. Note: If the Code Secret cannot be safely stored, you will need to implement the PKCE authorization flow, which is detailed in the Proof Key for Code Exchange (PKCE) Application Code Flow section below.
  2. Receive JSON Web Token (JWT)
    1. Using the Client ID and Client Secret that you received after registering your application in an exchange with the Identity Server to receive your JSON Web Token (JWT).

Standard Authorization Code Flow

  1. Connect to the Patient Access API
    1. In the standard authorization code flow, you will first need to use the OAuth 2.0 and OpenID Connect (OIDC) flow for authentication.
    2. This flow should only be used by sites that can safely protect the Client ID and Client Secret, namely sites that operate on a secured server.
  2. Send Authorization Request
    1. Once your application has been selected by an AmeriHealth Caritas member, the application will send a request to the authorize end point.
    2. The AmeriHealth Caritas member will then be prompted with a login screen.
    3. After the AmeriHealth Caritas member logs in, they will authorize the data that your application will be able to access on their behalf.

Upon the AmeriHealth customer successfully logging in and providing authorization, the Identity Server will redirect the user back to your application at your redirect URI, and the authorization code will be included in the query parameters. The authorization code can then be exchanged for a JWT. The JWT should be included in FHIR requests as an authentication bearer token (within the request header). This token gives your application access to the FHIR server on behalf of the AmeriHealth Caritas customer that logged in, allowing you to pass data back to the AmeriHealth Caritas customer.

Request authorization from user

To allow a user to authorize your application, direct them to AmeriHealth Caritas /authorize endpoint:

This allows the user to securely login on behalf of your application.

The request must include the response_type set to code, your application's client_id,your application's redirect_uri and scope. In addition, you will need state and nonce fields that your application can use to identify the authorization request.

The following is an example of a web application's authorization request:

                    
                        GET
                        https://member.amerihealthcaritas.com/patientaccesssvc/oauth2/v1/authorize?response_type:code&client_id :xxx&redirect_uri:https://myhealthapp.com/return&scope:openid%20https%3A%2F%2Feapics.amerihealthcaritas.com %2Fpatient%2F*%2Ffhir%2Fpatient%2F*.read%20https%3A%2F%2Feapics.amerihealthcaritas.com%2Fpatient%2F*%2Ffhir% 2FfhirUser%20https%3A%2F%2Feapics.amerihealthcaritas.com%2Fpatient%2F*%2Ffhir%2Flaunch%2Fpatient%20offline _access&state:1233366&nonce:56578
  1. response_type: code.
  2. client_id: Your application's Client ID.
  3. redirect_uri: The URL to which AmeriHealth Caritas will redirect the browser after authorization has been granted by the user.
  4. scope: openid fhirUser offline_access patient/*.read launch/patient
  5. state: An opaque arbitrary alphanumeric string your app adds to the initial request that AmeriHealth Caritas includes when redirecting back to your application.
  6. nonce: A random string that your application generates.

Exchange Code for Token

authorization request is sent, the AmeriHealth Caritas customer will be directed to an AmeriHealth Caritas login page via browser re-directs; here they wil input their AmeriHealth Caritas login credentials to authenticate themselves Once successfully signed in the AmeriHealth Caritas customer will be presented with an authorization page. Once authorized, your application.

can exchange the code provided in the redirected request for a full token to make calls to the AmeriHealth Caritas FHIR server.

You will send a POST request to the AmeriHealth Caritas /token endpoint: POST

https://eapics.amerihealthcaritas.com/oauth2/v1/token

The POST request must contain the following in the request body as shown in the sample curl request:


                        curl - -request POST 'https://eapics.amerihealthcaritas.com/oauth2/v1/token' \
                        - -header 'Authorization: Basic client_id:client_secret' \
                        - -header 'Content-Type: application/x-www-form-urlencoded' \
                        - -data 'grant_type=authorization_code' \
                        - -data 'code=YOUR_AUTHORIZATION_CODE' \
                        - -data 'redirect_uri=YOUR_APP/callback'

The response body will contain the following:


                        {
                        "access_token": "xxxxxx",
                        "refresh_token": "xxxxxyyy",
                        "patient": "123",
                        "scope": "openid fhirUser offline_access patient/*.read launch/patient",
                        "id_token": "xX808xkjoughou8989jiOJkIOUnogjourKJOIJOo88098n8",
                        "token_type": "bearer",
                        "expires_in": 3600
                        }

You can now use this token within the request header in your calls to the AmeriHealth Caritas FHIR server.

Request Authorization from User

The following is an example of a mobile application's authorization request


                        GET
                        https://member.amerihealthcaritas.com/patientaccesssvc/oauth2/v1/authorize?response_type:code&clie nt_id:xxx&redirect_uri:https://myhealthapp.com/return&scope:openid%20https%3A%2F%2Fea pics.amerihealthcaritas.com%2Fpatient%2F*%2Ffhir%2Fpatient%2F*.read%20https%3A%2F%2Feapics.amerihealthcaritas.com%2 Fpatient%2F*%2Ffhir%2FfhirUser%20https%3A%2F%2Feapics.amerihealthcaritas.com%2Fpatient%2F*%2Ffhir%2F launch%2Fpatient%20offline_access&state:1233366&nonce:56578&code_challenge:axxccxx:&c ode_challenge_method:S256
  1. response_type: code.
  2. code_challenge: Generated challenge from the code_verifier.
  3. code_challenge_method: s256.
  4. client_id: Your application's Client ID.
  5. redirect_uri: The URL to which AmeriHealth Caritas will redirect the browser after authorization has been granted by the user. The Authorization Code will be available in the code URL parameter.
  6. scope: openid fhirUser offline_access patient/*.read launch/patient
  7. state: An opaque arbitrary alphanumeric string your app adds to the initial request that AmeriHealth Caritas includes when redirecting back to your application.
  8. nonce: A random string that your application generates.

Exchange Code for Token

After sending the authorization request, the AmeriHealth Caritas customer will be directed to a AmeriHealth Caritas sign in page through browser re-directs, where they will provide their AmeriHealth Caritas credentials to authenticate themselves. Upon completing sign-in, the AmeriHealth Caritas customer will be presented with an authorization page. Once the customer authorizes your application, your application can now exchange the code provided in the redirected request for a full token to make calls to the AmeriHealth Caritas FHIR server.

You will send a POST request to the AmeriHealth Caritas /token endpoint: POST

https://eapics.amerihealthcaritas.com/oauth2/v1/token

The POST request must contain the following in the request body as shown in the sample curl request:

                    
                        curl - -request POST 'https://eapics.amerihealthcaritas.com/oauth2/v1/token' \
                        - -header 'Authorization: Basic client_id:client_secret' \
                        - -header 'Content-Type: application/x-www-form-urlencoded' \
                        - -data 'grant_type=authorization_code' \
                        - -data 'code=YOUR_AUTHORIZATION_CODE' \
                        - -data 'redirect_uri=YOUR_APP/callback'

The response body will contain the following:


                        {
                        "access_token": "xxxxxx",
                        "refresh_token": "xxxxxyyy",
                        "patient": "123",
                        "scope": "openid fhirUser offline_access patient/*.read launch/patient",
                        "id_token": "xX808xkjoughou8989jiOJkIOUnogjourKJOIJOo88098n8",
                        "token_type": "bearer",
                        "expires_in": 3600
                        }

Best Practices for Payers and App Developers

The United States Core Data for Interoperability (USCDI)
Da Vinci Payer Data Exchange
CARIN Blue Button Implementation Guide
OpenID Connect Core 1.0 incorporating errata set 2
SMART App Launch Framework