Getting Started

Quick Start In 5 Easy Steps

This walkthrough guide takes you from “Connect health records” to your first successful API request.

Before you start

✅ Recommended:

If you haven’t read the prerequisites guide on What you Need Before you Start, please do so.

You should have:

  • Client ID and Client Secret from Consolidate Health

  • At least one preregistered Redirect URI

  • A backend endpoint capable of calling the token endpoint securely

You will be working with these base URLs:

  • Authorization: https://app.consolidate.health/connect/api/v1/authorize

  • Token: https://app.consolidate.health/connect/api/v1/token

  • API base: https://app.consolidate.health/connect/api/v1


Step 1: Redirect the patient to the authorization endpoint

When the patient clicks “Connect health records”, your app constructs an authorization URL and redirects the user to it.

Required query parameters

  • client_id

  • redirect_uri (must match preregistered url exactly)

  • scope (use both scopes: patient:read-all offline_access)

  • state (random value; store and validate later)

  • email

  • first_name

  • last_name

What to do in your app

  1. Generate a random state

  2. Store it temporarily (session, signed cookie, or server-side store)

  3. Redirect the browser to the authorization URL

Example (browser test)
<https://app.consolidate.health/connect/api/v1/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_URL_ENCODED_REDIRECT_URI&scope=patient%3Aread-all%20offline_access&state=RANDOM_STATE_VALUE&email=USER_EMAIL&first_name=USER_FIRST_NAME&last_name=USER_LAST_NAME>
<https://app.consolidate.health/connect/api/v1/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_URL_ENCODED_REDIRECT_URI&scope=patient%3Aread-all%20offline_access&state=RANDOM_STATE_VALUE&email=USER_EMAIL&first_name=USER_FIRST_NAME&last_name=USER_LAST_NAME>
<https://app.consolidate.health/connect/api/v1/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_URL_ENCODED_REDIRECT_URI&scope=patient%3Aread-all%20offline_access&state=RANDOM_STATE_VALUE&email=USER_EMAIL&first_name=USER_FIRST_NAME&last_name=USER_LAST_NAME>

Important implementation notes

  • URL-encode values (especially redirect_uri and email)

  • Store state so you can verify it in Step 3

  • The user leaves your app during this flow


Step 2: The patient completes the Consolidate Health flow

Consolidate Health guides the patient through the hosted experience, which includes:

  • Onboarding and email verification

  • Provider identification (AI-guided survey)

  • Connecting one or more EHR portals

  • Reviewing and approving sharing with your application

At the end of this step, Consolidate Health redirects the patient back to your app.


Step 3: Handle the authorization callback

After approval, the patient is redirected to your registered redirect_uri with these query parameters:

  • code (authorization code)

  • state (should match the value from Step 1)

  • scope

Example
<https://your-preregistered-callback-url>


<https://your-preregistered-callback-url>


<https://your-preregistered-callback-url>
What your app must do

  1. Read code and state from the callback request

  2. Verify the returned state matches what you stored in Step 1

    • If it does not match, stop and treat it as a failed/unsafe authorization attempt.

ℹ️ Non-technical explanation:

This is the “return trip.” You’re confirming the patient came back from the exact authorization you initiated, not from a forged redirect.


Step 4: Exchange the authorization code for tokens (backend only)

Your backend exchanges the code for tokens by calling the token endpoint using HTTP Basic Authentication with client_id:client_secret.

cURL Example
curl -X POST <https://app.consolidate.health/connect/api/v1/token> \\
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \\
  -H "Content-Type: application/x-www-form-urlencoded" \\
  --data-urlencode "grant_type=authorization_code" \\
  --data-urlencode "code=AUTHORIZATION_CODE_FROM_CALLBACK" \\
  --data-urlencode "redirect_uri=YOUR_REDIRECT_URI"
curl -X POST <https://app.consolidate.health/connect/api/v1/token> \\
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \\
  -H "Content-Type: application/x-www-form-urlencoded" \\
  --data-urlencode "grant_type=authorization_code" \\
  --data-urlencode "code=AUTHORIZATION_CODE_FROM_CALLBACK" \\
  --data-urlencode "redirect_uri=YOUR_REDIRECT_URI"
curl -X POST <https://app.consolidate.health/connect/api/v1/token> \\
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \\
  -H "Content-Type: application/x-www-form-urlencoded" \\
  --data-urlencode "grant_type=authorization_code" \\
  --data-urlencode "code=AUTHORIZATION_CODE_FROM_CALLBACK" \\
  --data-urlencode "redirect_uri=YOUR_REDIRECT_URI"
Example response
{
  "access_token": "ory_at_...",
  "expires_in": 21600,
  "refresh_token": "ory_rt_...",
  "scope": "patient:read-all offline_access",
  "token_type": "bearer",
  "patient_id": "0d421a99-a7db-42a3-b3fd-c64ecaaf01c1"
}
{
  "access_token": "ory_at_...",
  "expires_in": 21600,
  "refresh_token": "ory_rt_...",
  "scope": "patient:read-all offline_access",
  "token_type": "bearer",
  "patient_id": "0d421a99-a7db-42a3-b3fd-c64ecaaf01c1"
}
{
  "access_token": "ory_at_...",
  "expires_in": 21600,
  "refresh_token": "ory_rt_...",
  "scope": "patient:read-all offline_access",
  "token_type": "bearer",
  "patient_id": "0d421a99-a7db-42a3-b3fd-c64ecaaf01c1"
}
What to store

Store these server-side (securely):

  • access_token

  • refresh_token

  • expires_in

  • patient_id

⚠️ Critical

Do not put the client secret in browser code. Do not call /token from the frontend!


Step 5: Make your first API request

With the access_token and patient_id, you can call patient endpoints.

Example: Medications
curl "<https://app.consolidate.health/connect/api/v1/patients/PATIENT_ID/medications?limit=20>" \\
  -H "Authorization: Bearer ACCESS_TOKEN" \\
  -H "Accept: application/json"
curl "<https://app.consolidate.health/connect/api/v1/patients/PATIENT_ID/medications?limit=20>" \\
  -H "Authorization: Bearer ACCESS_TOKEN" \\
  -H "Accept: application/json"
curl "<https://app.consolidate.health/connect/api/v1/patients/PATIENT_ID/medications?limit=20>" \\
  -H "Authorization: Bearer ACCESS_TOKEN" \\
  -H "Accept: application/json"

If this returns a 200 OK with JSON, your integration is working end-to-end.

Token refresh (required for production integrations)

Access tokens expire (the current guide indicates 6 hours). Use the refresh token to obtain a new access token.

Refresh example
curl -X POST <https://app.consolidate.health/connect/api/v1/token> \\
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \\
  -H "Content-Type: application/x-www-form-urlencoded" \\
  --data-urlencode "grant_type=refresh_token" \\
  --data-urlencode "refresh_token=YOUR_REFRESH_TOKEN"
curl -X POST <https://app.consolidate.health/connect/api/v1/token> \\
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \\
  -H "Content-Type: application/x-www-form-urlencoded" \\
  --data-urlencode "grant_type=refresh_token" \\
  --data-urlencode "refresh_token=YOUR_REFRESH_TOKEN"
curl -X POST <https://app.consolidate.health/connect/api/v1/token> \\
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \\
  -H "Content-Type: application/x-www-form-urlencoded" \\
  --data-urlencode "grant_type=refresh_token" \\
  --data-urlencode "refresh_token=YOUR_REFRESH_TOKEN"

Recommended behavior:

  • On 401 Unauthorized, refresh the token and retry once.

  • If refresh fails, prompt the user to reconnect.


Common pitfalls and how to avoid them

Redirect URI mismatch

If the redirect_uri you send does not match exactly what was preregistered, authorization will fail. Keep a single source of truth for the redirect URI string.

State validation skipped

If you don’t validate state, you risk accepting forged callbacks. Always validate.

Token exchange attempted in frontend

This will fail due to security constraints and may surface as CORS issues. Always exchange the code on the backend.

Old authorization code

Authorization codes are time-limited. If a user restarts the flow or token exchange takes too long, restart at Step 1.

What You Need Before You Start

What You Need Before You Start

What You Need Before You Start

First Successful API Call

First Successful API Call

First Successful API Call