Quickstart
Flexpa Link can be used in an app to authorize access to health plans, claims,
and clinical data. Then, Flexpa API can be used to query electronic medical
records via FHIR Resources.
See this in action by building and running Flexpa's quickstart application hosted on GitHub.
After that, continue reading to learn how the application works so you can modify this example for your own uses.
#Quickstart setup
Let's start by getting the quickstart project running locally on your machine.
This section walks through cloning the quickstart repo, setting your API keys, running the project, and testing it.
#Clone repo
First, clone the quickstart repository:
Clone
# Clone the quickstart repository
git clone https://github.com/flexpa/quickstart.git
#Set API keys
Flexpa integrations run in one of two modes, determined by the keys used. Test mode functions like live mode, except the data returned is not real patient data. When you've finished testing, simply swap in your live mode keys!
Each mode uses a pair of API keys: a publishable key, that can be used publicly, and a secret key, that must be kept private.
Create an account in the Flexpa Portal to get test mode keys and contact us for live mode access.
A client-side key that uniquely identifies your app
A server-side key that uniquely identifies your integration's back end
You must use the test mode publishable key with the test mode secret key and the live mode publishable key with the live mode secret key.
You'll need to add your publishable and secret API keys to the .env files in the client and server directories.
Rename the .env.template file as .env in both directories.
cd quickstart
cp client/.env.template client/.env
cp server/.env.template server/.env
Open both client/.env and server/.env and add your test mode API keys.
client/.env
VITE_FLEXPA_PUBLISHABLE_KEY=
server/.env
FLEXPA_API_SECRET_KEY=
#Run project
The quickstart code includes two components:
- Frontend client for creating the Flexpa Link connection to a health plan
- Backend server that swaps a public token for an access token
Run both components simultaneously to test the application.
From the root of the project, run the frontend client:
# Navigate into the client directory
cd client
# Set the correct node version
nvm use
# Install the dependencies
npm install
# Run the frontend server
npm run dev
Next, from the root of the project in a new terminal, run the backend server:
# Navigate into the server directory
cd server
# Set the correct node version
nvm use
# Install the dependencies
npm install
# Compile the TypeScript to JavaScript code
npm run build
# Run the backend server
npm run dev
#Test application
To test the quickstart app:
- Open http://localhost:3000 in your browser.
- Click the "Connect your health plan with Flexpa Link" to open the Flexpa Link modal.
- Select any health plan payer from the list.
- When directed to the provider's site, authenticate using a test mode login.
- When Flexpa Link indicates success, click "Continue".
Upon successful authentication, you'll be redirected back to localhost. The server script automatically exchanges the public token for an access token, and then the client app performs a FHIR request and reports upon the result. (This may take a moment to complete.)
#How it works
Now that you've seen the application in action, let's examine 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 the publishableKey and onSuccess parameters to configure Flexpa Link:
client/src/main.ts
FlexpaLink.create({
publishableKey: import.meta.env.VITE_FLEXPA_PUBLISHABLE_KEY, // Defined in .env
onSuccess: async (publicToken: string) => {},
// ^ We'll talk about the onSuccess callback later
});
#Authentication flow
The Flexpa authentication flow helps you obtain authorization to access health plans, 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 FlexpaLink.open().
Once clicked, the button presents the user with a modal to connect their health plan payer:
#Obtain access token
After a user completes the payer login flow, the onSuccess callback is executed, with a publicToken as the argument.
To query patient data, you must exchange the public token for an access token using your secret API key (i.e., from the server).
Here's an updated Flexpa Link configuration with that callback definition:
client/src/main.ts
FlexpaLink.create({
publishableKey: import.meta.env.VITE_FLEXPA_PUBLISHABLE_KEY,
onSuccess: async (publicToken: string) => {
/* Make a request to the `POST /flexpa-access-token` endpoint
defined in `server`.
Include the `publicToken` in the body. */
const resp = await fetch(
`${import.meta.env.VITE_SERVER_URL}/flexpa-access-token`,
{
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ publicToken }),
}
);
},
});
After the server swaps the public token for an access token you can use the access token to query Flexpa API for patient data. 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.
- Pass the access token back to the client.
- The client can now query Flexpa API using the wildcard parameter
$PATIENT_ID!
Here is a minimal endpoint that performs the token exchange:
server/src/routes/flexpa_api_token.ts
/**
* POST /flexpa-access-token
* Exchanges your `publicToken` for an `access_token`
*/
router.post("/flexpa-access-token", async (req: Request, res: Response) => {
const { publicToken } = req.body as FlexpaAccessTokenBody;
...
// Call Flexpa API's exchange endpoint to exchange
// your `publicToken` for an `access_token`
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, expires_in: expiresIn } = await resp.json() as LinkExchangeResponse;
res.send({ accessToken, expiresIn });
}
catch (err) {
return res.status(500).send(`Error exchanging token: ${err}`);
}
});
Once your client receives the access token, it has everything needed to access patient data using Flexpa API.
#Flexpa API FHIR queries
Once the application has the access token it can make requests to the patient's payer FHIR server through https://api.flexpa.com/fhir. All FHIR Resource requests must include the access token within the Authorization HTTP header.
For FHIR endpoints that need a patient ID, Flexpa API automatically pulls the patient ID from the access token when you use the wildcard parameter $PATIENT_ID.
Flexpa API supports reading and searching a variety of FHIR Resources. 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 // https://api.flexpa.com/fhir
}/Coverage?patient=$PATIENT_ID`,
{
method: "GET",
headers: {
authorization: `Bearer ${accessToken}`,
},
}
);
#Next steps