Quickstart
Get started with a cloneable quickstart project
Goal
Flexpa Link can be used in an app to authorize access to health plan, claims,
and clinical data. Then, Flexpa API can be used to query electronic medical
records via FHIR resources.
This guide shows you how to build and run Flexpa's quickstart example on GitHub.
Quickstart Setup
Let's start by getting the quickstart project running locally on your machine.
This section will walk through getting the API keys, cloning the quickstart repo, and running the project.
Get API Keys
To use Flexpa, you will need valid API keys.
- You can generate Test Mode API keys (recommended for development)
- or contact us for production access.
Once you have the API keys, you're ready to go!
Make sure you have NodeJS and npm
installed on your machine before beginning the setup.
You will also need a terminal capable of running basic Unix commands.
Clone Repo
First, clone the quickstart repository. You can do this using HTTPS:
git clone https://github.com/flexpa/quickstart.git
cd quickstart
Set Environment Variables
You'll need to add your publishable and secret Flexpa API keys to a .env
file in the client and server directories.
Rename the file .env.template
to .env
in both directories and update the values to your publishable and secret keys.
cp client/.env.template client/.env
cp server/.env.template server/.env
During development, you will need to use the Test Mode API keys rather than
the production ones.
Open both client/.env
and server/.env
in a text editor and replace the values with your Test Mode API keys. Remember to save!
client/.env
VITE_FLEXPA_PUBLISHABLE_KEY=
server/.env
FLEXPA_API_SECRET_KEY=
Run the Project
First, from the root of the project, run the frontend client:
cd client
nvm use
npm install
npm run dev
Next, from the root of the project in a new terminal, run the backend server:
cd server
nvm use
npm install
npm run build
npm run dev
Note: nvm
is not supported on Windows. If you are using Windows, ensure
you have the correct version of Node installed. See
.nvmrc
for
the recommended version.
Open http://localhost:3000 with your browser to see the result.
You can use the following test patient login with Humana:
How It Works
Now that you have the quickstart project running, let's step through some of the main sections.
Flexpa Link Configuration
Flexpa Link is included through a script tag inside the head of the HTML
document:
client/index.html
<html>
...
<head>
...
<script src="https://js.flexpa.com/v1/"></script>
...
</head>
...
</html>
Then, in the client-side Javascript code,
FlexpaLink.create()
is called with parameters to configure Flexpa Link:
client/src/main.ts
FlexpaLink.create({
publishableKey: import.meta.env.VITE_FLEXPA_PUBLISHABLE_KEY,
onSuccess: async (publicToken: string) => {},
});
Triggering the Authentication Flow
The Flexpa authentication flow helps you obtain authorization to access health plan, coverage, and clinical data directly from a patient.
Read more about which plans Flexpa supports in our Endpoints reference.
To start the authentication flow, FlexpaLink.open()
is called within the onclick
handler of a button.
client/src/main.ts
const linkButton = document.getElementById("flexpa-link-btn");
...
linkButton.addEventListener("click", () => {
FlexpaLink.open();
});
You must call FlexpaLink.create(...)
before calling Flexpa.open()
Once clicked, it presents the user with a modal to link their health plan payer:

Obtaining an Access Token
After a user completes the payer login flow, the onSuccess
callback is executed, with a public_token
as the argument.
client/src/main.ts
FlexpaLink.create({
publishableKey: import.meta.env.VITE_FLEXPA_PUBLISHABLE_KEY,
onSuccess: async (publicToken: string) => {
const resp = await fetch(
`${import.meta.env.VITE_SERVER_URL}/flexpa-access-token`,
{
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ publicToken }),
}
);
},
});
To query patient data, you must exchange the public token for an access token. You can then use the access token to query Flexpa API for patient data.
Visually, the flow looks like:
To exchange the public token for an access token, you must:
- Pass the public token to your server
- Have your server make a
POST
request to https://api.flexpa.com/link/exchange
, passing the public token and your secret key within the JSON body
- Parse the response JSON body of
https://api.flexpa.com/link/exchange
to extract the access token and patient id
- Pass the access token and patient id back to the client
- The client now has everything it needs to query patient health data!
A minimal endpoint that facilitates the token exchange might look like this:
server/src/routes/flexpa_api_token.ts
router.post("/flexpa-access-token", async (req: Request, res: Response) => {
const { publicToken } = req.body as FlexpaAccessTokenBody;
...
try {
const resp = await fetch(`${process.env.FLEXPA_PUBLIC_API_BASE_URL}/link/exchange`, {
method: "POST",
headers: {
"content-type": "application/json",
},
body: JSON.stringify({
public_token: publicToken,
secret_key: process.env.FLEXPA_API_SECRET_KEY,
}),
});
const { access_token: accessToken, patient_id: patientId, expires_in: expiresIn } = await resp.json() as LinkExchangeResponse;
res.send({ accessToken, patientId, expiresIn });
}
catch (err) {
return res.status(500).send(`Error exchanging token: ${err}`);
}
});
Once your client receives the access token and patient id, it has everything needed to access patient data using Flexpa API.
Flexpa API FHIR Queries
Now that the application has the access token and patient id, it can make requests to the patient's payer FHIR server through https://api.flexpa.com/fhir
.
Any FHIR resource requests must include:
patientId
in the query parameter and
accessToken
within the authorization
HTTP header
Flexpa API supports reading and searching a variety of FHIR resources.
See FHIR resources for some examples of the resources we support.
The quickstart example retrieves the Coverage FHIR resource:
client/src/main.ts
const fhirResp = await fetch(
`${
import.meta.env.VITE_FLEXPA_PUBLIC_FHIR_BASE_URL
}/Coverage?patient=${patientId}`,
{
method: "GET",
headers: {
authorization: `Bearer ${accessToken}`,
},
}
);
Next Steps
See the API documentation or follow one of our guides for more information on requesting users' health data.