Health plan login guide

Patients can directly verify their health plan to your app by completing a login.

After granting your application access, your app can:

You can do this by:

  • using the <FlexpaLogin /> React component + one our examples to test a demo
  • writing a FHIR query and using flexpa/gateway to resolve and return the right health plan data for your application

This guide will focus on retrieving the status of a plan using <FlexpaLogin /> and <CovergageCard /> - two of our our out-of-the-box React components.


Install @flexpa/login:

npm install --save @flexpa/login

Adding the FlexpaLogin component

Import the component and render it on a page:

import { FlexpaLogin } from "@flexpa/login"

export default <FlexpaLogin sandbox />

Patients are expected to search for their health plan to initiate the login process. Your <FlexpaLogin sandbox /> example should render like this:


Each health plan login presented to the user is technically a CARIN IG for Blue Button (CARIN BB API). When the CMS released the Interoperability and Patient Access rule in May 2020, it established a requirement to create and provider a Patient Access API for CMS regulated payers (aka CARIN BB).

  • Flexpa federates your app's access to all of the existing CARIN BB APIs
  • Plans covered include Medicare Advantage (MA), Medicaid, Children's Health Insurance Program (CHIP), and Qualified Health Plan (QHP) issuers on the Federally Facilitated Exchanges (FFEs)
  • You can read more about our which plans Flexpa supports on our Endpoints reference

The benefit to developers of using Flexpa as an interface to health plan data:

  • Authorization process is consistent (SMART)
  • Data schema and API across health plans is consistent (CARIN BB)

Completing a login

After patients identify their health plan, and successfully completes an authenticated login, FlexpaLogin receives a verification token.

This verification token is signed by Flexpa and contains all of the information necessary to succesfully request data granted by the patient, including:

  • iss the protocol and hostname of the health plan
  • aud the downstream FHIR server that accepts this verification token

This verification token must be kept secure because you will use it to retrieve patient data.

You can read more about using Flexpa's FHIR React Hooks + flexpa/gateway to automatically route FHIR requests to the right destination. But we can improve our demo with a pre-built example that does this for us.

Showing plan info

After a patient has completed a login, let's display some information about their health plan.

Coverage is the basic resource that explains a health plan that you retrieve from a FHIR API after being granted access by a patient.

  • Coverage.status can be active, cancelled, draft, or entered-in-error

We can use Coverage.status to determine if a given health plan is currently valid.

Below, you can see an example of <CoverageCard /> being rendered. We will walk through how to recreate this example.

Image of a CoverageCard component

To build this you will need two of our components:

  • FlexpaLogin - to prompt the Patient to login to their health plan system & grant API access.
  • CoverageCard - To query & view the Coverage after we have been granted API access.


import { FlexpaLogin, CoverageCard } from '@flexpa/login';

  <CoverageCard />

Live Demo


You can complete a full end to end patient login experience by clicking on the pre-loaded Humana example above. Use these credentials: HUser00002 and PW00002! for a test Humana health plan.

Image of the Humana claim process

Humana demonstrates a standardized login flow that all patients will experience. Patients participate in an informed consent process (reference: OAuth scopes), granting your application access to health care data like Coverage.

After the Patient accepts, our <CoverageCard /> component will be rendered. Showing some metadata around the Patient's Coverage, status included. It should look similar to this (same image as above):

Image of a CoverageCard component

You have now verified a patient's health plan using Flexpa! We can see from their Coverage.status that it is active 🎉

Where to next?



  • FlexpaEndpoint and Medicare Advantage plans