AdvancedMD

AdvancedMD (Global Payments)

AdvancedMD

Read-only OAuth 2.0 + FHIR R4 (USCDI v3) integration adapter for AdvancedMD. Supports patient/provider standalone, EHR (embedded) launch, and SMART Backend Services Bulk export. FHIR access is read-only per Cures Act §170.315(g)(10) — write-back requires AdvancedMD's separate Partner API.

AdvancedMD (Global Payments) FHIR R4 standalone-oauth backend-jwt smart-on-fhir

Overview

ConnectHealth's AdvancedMD integration gives your application secure access to patient data through AdvancedMD's SMART on FHIR (OAuth 2.0 + FHIR R4) APIs. ConnectHealth acts as the middleware layer — handling authentication, token lifecycle, and FHIR communication — so your team can focus on building features rather than managing EHR-specific OAuth flows.

⚠

AdvancedMD FHIR is READ-ONLY

AdvancedMD's FHIR APIs follow the Cures Act §170.315(g)(10) standard, which is read-only (GET/search). You can read and search patient data and run Bulk Data exports, but you cannot create, update, or delete FHIR resources. Writing data back to AdvancedMD requires AdvancedMD's separate (paid) Partner API, which is out of scope for this integration.

ℹ

Application Ownership

You (your organization) must create and own the AdvancedMD applications. ConnectHealth is middleware — it does NOT create apps, manage AdvancedMD accounts, or submit applications on your behalf. You must have an AdvancedMD app whose API access has been authorized by AdvancedMD's Interoperability (InterOps) team, with Client key/secret in hand, before configuring any workflow in ConnectHealth.

Supported Authentication Flows

Click a card to jump to its configuration section.

Standalone OAuth

Standard OAuth 2.0 authorization code flow where patients or providers authorize access to their data via AdvancedMD. Uses the FHIR Single Patient API. Best for patient portals and provider-facing apps needing user consent.

Embed Launch

SMART on FHIR EHR launch flow for apps launched from within AdvancedMD. The app receives patient context automatically via the launch parameter. Also uses the FHIR Single Patient API. Best for in-context clinical tools.

Backend (Bulk Export)

SMART Backend Services flow for server-to-server population exports without user interaction. Uses the FHIR Bulk API with a signed JWT plus provider credentials. Best for bulk/population data retrieval.

Key Features

FHIR resource search and read (READ-ONLY — no create/update/delete)
Bulk Data export ($export) via SMART Backend Services
Backend auth = RS384 JWT client assertion + username/password/officekey
Per-organization FHIR base URL (org_id in the path)
PKCE (S256) supported for authorization-code flows
Token refresh
Audit logging for all operations

Before You Begin

Before you can use AdvancedMD with ConnectHealth, you must register an application on the AdvancedMD Developer Portal and have its API access authorized by AdvancedMD's InterOps team. This section outlines the prerequisites.

Prerequisites Checklist

✓ AdvancedMD developer account — Create one at the AdvancedMD FHIR Developer Portal (verify your email within 10 minutes of signup)
✓ Registered application(s) — Each app requests exactly one product: FHIR Single Patient API (for Standalone + Embed) and/or FHIR Bulk API (for Backend)
✓ InterOps authorization — File a "Have a FHIR Question" ticket so AdvancedMD authorizes your app's API access; you receive a Client key/secret
✓ Organization Base URL / org_id — AdvancedMD FHIR base URLs are per-organization (e.g. test orgs 174 / 175)
✓ Redirect URI configured — Registered in your AdvancedMD app (provided by ConnectHealth)
✓ For Backend (Bulk) — An RSA key pair (RS384) registered with AdvancedMD, plus the provider's username, password, and officekey

Create Your AdvancedMD Application

Follow these steps to register your AdvancedMD application. Your organization owns and manages this app on the AdvancedMD Developer Portal.

Create an AdvancedMD Developer Account

Go to the AdvancedMD FHIR Developer Portal → Sign In → Create account.

Provide your email, name, and password, and accept the Terms & Conditions
Verify your email within 10 minutes (the link expires; you can resend from the portal)
Your organization owns this account and all apps created under it

Create Your Application(s) — One Product Per App

Click your email (top right) → Apps → New app. Fill in the App name and Description, then request exactly one product per app:

For Standalone + Embed Launch: request FHIR Single Patient API
For Backend (Bulk export): request FHIR Bulk API

Do not request more than one product per app. Standalone/Embed and Backend therefore live in separate apps.

Get InterOps Authorization for Your App

Newly created apps are not usable until AdvancedMD's Interoperability team authorizes their API access. After creating your app(s):

Open AdvancedMD's InterOps Support page and submit a ticket using the "Have a FHIR Question" option
Reference each app name (and app ID) so the team can find and authorize it
Wait for confirmation that API access has been enabled

Retrieve Your Credentials and Org Base URL

Once authorized:

Open each app and copy its Client key (Client ID) and Client secret
Request the Organization Base URL / org_id for the practice you'll connect to (test orgs 174/175 are available in the sandbox; the production org list is downloadable as CSV / FHIR Bundle and is updated quarterly)
Register your ConnectHealth Redirect URI in the app (you get the exact value from ConnectHealth after creating your connection)

Configure in ConnectHealth

Now create your AdvancedMD connection in ConnectHealth:

In ConnectHealth, navigate to Connections and create a new connection
Select AdvancedMD as the EHR type
Select your workflow type — Standalone, Embed Launch, or Backend
Paste your Client ID / Client Secret, and the AdvancedMD endpoints + per-org Base URL (see the Configuration Reference below)
Copy the generated Redirect URL from ConnectHealth into your AdvancedMD app
Save your connection

Test with Sandbox Data

Validate your integration using the portal's built-in Smart App launch tester and Test data (test orgs 174/175, with test patient and provider logins). See Sandbox Environment Setup below.

Sandbox Environment Setup

AdvancedMD provides a sandbox directly on the Developer Portal. Use the built-in Smart App launch page to choose scopes, run the test app, and obtain an access token, then exercise the FHIR APIs from the API documentation's "Try this API" panel. You still need your own InterOps-authorized app's Client key/secret.

Sandbox Test Organizations

The portal exposes test Organization Base URLs. Each is a complete, per-organization FHIR R4 base URL.

Test Organization	Base URL
FHIR PRACTICE GROUP TEST	`https://providerapi.advancedmd.com/v1/r4/174`
FHIR PRACTICE GROUP TEST 2	`https://providerapi.advancedmd.com/v1/r4/175`

AdvancedMD OAuth + FHIR Endpoints

These are fixed for AdvancedMD. Enter them in ConnectHealth when configuring a connection (the Base URL is per-organization — append your org_id).

Purpose	URL
OAuth Authorization	`https://providerapi.advancedmd.com/v1/oauth2/authorize`
OAuth Token	`https://providerapi.advancedmd.com/v1/oauth2/token`
FHIR Base (R4, per-org)	`https://providerapi.advancedmd.com/v1/r4/{org_id}`
Bulk export kickoff	`https://providerapi.advancedmd.com/v1/r4/Group/{GroupId}/$export`

✅

The Base URL must include your organization id

AdvancedMD FHIR base URLs are per-organization: .../v1/r4/{org_id}. FHIR resource requests look like https://providerapi.advancedmd.com/v1/r4/174/Patient/12345. If you don't know your organization's org_id, request it from AdvancedMD InterOps Support.

Configuration Reference

Complete the steps above (register your app and get its API access authorized by AdvancedMD InterOps) before filling in these fields. You will need your Client ID, Client Secret, and your organization's Base URL.

ConnectHealth supports multiple workflow types for this integration. Choose the one that matches your use case.

Standalone OAuth

Standard OAuth 2.0 authorization code flow (FHIR Single Patient API) where patients or providers authorize access via AdvancedMD. Confidential clients authenticate with HTTP Basic; PKCE (S256) is also supported. Best for patient portals and provider-facing apps.

Field	Autofill	Required	Description
`Client ID`	No	Yes	Your application's Client key from the AdvancedMD Developer Portal.
`Client Secret`	No	Yes	Client secret for confidential clients (used for HTTP Basic auth). Keep this secure.
`Authorization URL`	No	Yes	`https://providerapi.advancedmd.com/v1/oauth2/authorize`
`Token URL`	No	Yes	`https://providerapi.advancedmd.com/v1/oauth2/token`
`FHIR Base URL`	No	Yes	Your per-org base URL: `https://providerapi.advancedmd.com/v1/r4/{org_id}`
`Scopes`	No	Yes	Space-separated scopes. The submodule auto-normalizes to include `openid` and `fhirUser`. Default: `openid fhirUser offline_access online_access patient/*.read`
`Redirect URL`	Yes	Yes	Your ConnectHealth callback URL, registered in your AdvancedMD app.

Setup Steps

Register an app requesting the FHIR Single Patient API product and get it authorized by InterOps.
Register your ConnectHealth redirect URI in the app.
Enter the AdvancedMD Authorization/Token URLs and your per-org FHIR Base URL in ConnectHealth.
Choose your scopes (openid and fhirUser are auto-added if missing).
Test by initiating a login — the user is redirected to AdvancedMD to authorize.

Backend (Bulk Export)

AdvancedMD's only system-to-system option is the FHIR Bulk API (SMART Backend Services). It uses the client_credentials grant with a signed RS384 JWT client assertion plus the provider's username, password, and officekey. Best for population/bulk data export via group $export.

Field	Autofill	Required	Description
`Client ID`	No	Yes	Your Bulk app's Client key from the AdvancedMD Developer Portal.
`Token URL`	No	Yes	`https://providerapi.advancedmd.com/v1/oauth2/token`
`FHIR Base URL`	No	Yes	Org-less root for Bulk: `https://providerapi.advancedmd.com/v1/r4` (do not append `{org_id}` — AdvancedMD's Bulk `$export` kickoff lives at `/v1/r4/Group/{id}/$export`).
`JWKS Private Key` + `kid`	Generate	Yes	RS384 key pair. Generate it in ConnectHealth (or upload your own) and register the public key with AdvancedMD.
`Username`	No	Yes	Provider's AdvancedMD username, sent with the client_credentials request.
`Password`	No	Yes	Provider's AdvancedMD password.
`Office Key`	No	Yes	The AdvancedMD office key (unique client identifier) for the provider.
`Scopes`	No	Yes	System-level scope. AdvancedMD Bulk allows only `system/*.read`.

Setup Steps

Register an app requesting the FHIR Bulk API product and get it authorized by InterOps.
Generate an RS384 key pair in ConnectHealth and register the public key with AdvancedMD.
Enter the Token URL, per-org FHIR Base URL, and the provider's username / password / officekey.
Set the scope to system/*.read.
Test by requesting a backend token, then kick off a group $export and poll the status URL.

SMART on FHIR - Embed Launch

SMART on FHIR EHR launch flow (FHIR Single Patient API) for apps embedded within AdvancedMD. The app is launched from the EHR and receives patient context automatically via the launch parameter.

Field	Autofill	Required	Description
`Client ID`	No	Yes	Your application's Client key from the AdvancedMD Developer Portal.
`Client Secret`	No	No	Client secret for confidential clients (optional).

Setup Steps

Register an app requesting the FHIR Single Patient API product (the same app can serve Standalone + Embed).
Register your ConnectHealth Launch URL where AdvancedMD sends the iss and launch parameters.
Configure the Embed Launch workflow in ConnectHealth with the Client ID (and optional Client Secret).
Your app handles the tokenId returned by ConnectHealth and calls the token exchange endpoint to retrieve the access token.
Test by launching your app from within AdvancedMD.

How to Handle SMART Launch

Once your Embed Launch app is configured, here's the end-to-end flow — from AdvancedMD initiating the launch to your app receiving a usable FHIR access token. Each step is tied to the exact ConnectHealth endpoint involved.

AdvancedMD Initiates the Launch

When a clinician opens your app from within AdvancedMD, it calls your registered Launch URL:

GET https://<your-ch-domain>/api/workflow/auth/{integrationId}/launch?iss=...&launch=...

iss — AdvancedMD's FHIR base URL (e.g., https://providerapi.advancedmd.com/v1/r4/174)
launch — an opaque token carrying patient context

No action needed from you — this is the URL you registered in the AdvancedMD app.

ConnectHealth Completes OAuth and Returns a `tokenId`

ConnectHealth exchanges the launch token with AdvancedMD server-side, stores the resulting access token securely, and redirects back to your embedded app with a short-lived, one-time-use tokenId.

Call Token Exchange to Retrieve the Access Token

Your app calls the Token Exchange endpoint with the tokenId. This endpoint requires the x-api-key header:

GET https://<your-ch-domain>/api/workflow/auth/{integrationId}/token/exchange/{tokenId}
Headers:
  x-api-key: <your-connecthealth-api-key>
  Accept: application/json

Response contains access_token, patient, scope, expires_in, and — if offline_access was requested — a refresh_token.

Call FHIR Using the Access Token (Read-Only)

Use the access_token as a Bearer token against your per-org FHIR base URL:

GET https://providerapi.advancedmd.com/v1/r4/{org_id}/Patient/{patient}
Headers:
  Authorization: Bearer {access_token}
  Accept: application/fhir+json

Remember: read/search only — AdvancedMD does not accept FHIR writes.

Refresh Before Expiry

Access tokens expire (typically in an hour). Before expiry, call the Token Refresh endpoint to obtain a new one without re-prompting the user. Like Token Exchange, this requires x-api-key:

POST https://<your-ch-domain>/api/workflow/auth/{integrationId}/token/refresh
Headers:
  x-api-key: <your-connecthealth-api-key>
  Content-Type: application/json

Body:
{
  "refresh_token": "<your-refresh-token>"
}

Refresh only works if offline_access was included in your requested scopes.

General Scopes

Scopes define the level of access your application requests. AdvancedMD scopes are based on USCDI v3. Choose them based on your workflow type and data needs.

Patient Scopes

Patient-level scopes grant access to the launched/authorized patient's data (Single Patient API).

Scope	Description
`patient/*.read`	Read all supported resource types for the patient (SMART v1 style)
`patient/*.rs`	Read and search all supported resource types for the patient (SMART v2 style)

User Scopes

User-level scopes grant access based on the permissions of the logged-in provider.

Scope	Description
`user/*.read`	Read all resource types the user has access to
`user/*.rs`	Read and search all resource types the user has access to

System Scopes (Bulk / Backend)

System-level scope for backend/server applications without a specific user context. Used with the Backend (Bulk Export) workflow.

Scope	Description
`system/*.read`	Read all resource types at the system level — the only scope AdvancedMD's Bulk API allows

Launch & Identity Scopes

Launch and OpenID Connect scopes. The submodule auto-adds openid and fhirUser if not present, and adds launch for EHR launch.

Scope	Description
`launch`	Required for EHR launch — receives the launch context from AdvancedMD (auto-added for embed)
`launch/patient`	Request patient context in a standalone launch
`openid`	Required for OpenID Connect — returns an ID token (auto-added)
`fhirUser`	Returns the FHIR resource URL of the authenticated user (auto-added)
`offline_access`	Request a refresh token for long-lived access
`online_access`	Request a session-scoped (online) refresh token

Use Cases

Choose the workflow type that best matches your application's needs. All AdvancedMD FHIR access is read-only.

Patient-Facing Applications

Scenario: A third-party app reads patient health data with the patient's explicit consent.

Recommended Workflow: Standalone OAuth (FHIR Single Patient API)

Best For: Patient portals, health tracking apps, care management tools

Recommended Scopes: openid fhirUser offline_access online_access patient/*.read launch/patient

Provider-Facing Applications

Scenario: A provider app reads data the logged-in clinician can access.

Recommended Workflow: Standalone OAuth or Embed Launch

Best For: Clinician dashboards, read-only chart viewers, decision-support tools

Recommended Scopes: openid fhirUser user/*.read

EHR-Embedded Applications

Scenario: An application launched from within AdvancedMD that receives patient context automatically.

Recommended Workflow: Embed Launch (SMART on FHIR)

Best For: In-context clinical viewers and read-only decision support

Recommended Scopes: launch openid fhirUser patient/*.read

Population / Bulk Data Export

Scenario: A server exports a group of patients' data without user interaction for analytics or reporting.

Recommended Workflow: Backend (Bulk Export) (FHIR Bulk API)

Best For: Population health analytics, reporting pipelines, data warehousing

Recommended Scopes: system/*.read

Get Your ConnectHealth API Key

Several ConnectHealth endpoints — Token Exchange, Backend Token, and Token Refresh — require a ConnectHealth API key passed as the x-api-key header. Without this header, these endpoints return 401 Unauthorized. Follow these steps to create your API key.

Log in to the ConnectHealth Dashboard

Open your ConnectHealth instance (the URL where your deployment is hosted) and sign in with your account credentials.

Navigate to Settings → API Keys

From the left navigation, click Settings, then open the API Keys tab. If you have never generated a key before, the list will be empty.

Create a New API Key

Click Create API Key, enter a descriptive name (e.g., advancedmd-prod-client or advancedmd-bulk-dev), and submit. Use one key per environment or per client application so you can rotate individual keys without affecting others.

Copy Your API Key

ConnectHealth saves your API key securely. You can view and copy the key value from Settings → API Keys at any time.

Use the Key in the `x-api-key` Header

Pass the key on every request to a protected endpoint using the header name x-api-key (lowercase, hyphenated). Example:

curl -X GET "https://<your-ch-domain>/api/workflow/auth/{integrationId}/token/exchange/{tokenId}" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

Endpoints requiring this header are listed in the API Endpoints section below.

API Endpoints

These are the ConnectHealth endpoints your application will interact with. All paths are prefixed with /api/workflow/auth/{integrationId}, where {integrationId} is the connection ID you created in ConnectHealth.

🔑

API Key Required on Token Endpoints

Token Exchange, Backend Token, and Token Refresh all require the x-api-key header. Create a key from Settings → API Keys before calling these endpoints.

Authentication Endpoints

Method	Endpoint	Description	API Key
`GET`	`/api/workflow/auth/{integrationId}/start`	Initiate OAuth flow for standalone launch. Typically hit from a browser; returns a redirect to AdvancedMD.	No
`GET`	`/api/workflow/auth/{integrationId}/callback`	OAuth redirect URI. Called by AdvancedMD after user authorization — not by your client. Exchanges the code for tokens and stores them, returning a one-time `tokenId`.	No
`GET`	`/api/workflow/auth/{integrationId}/launch`	SMART on FHIR EHR Launch URL. Called by AdvancedMD with `iss` and `launch` query params — not by your client.	No
`GET`	`/api/workflow/auth/{integrationId}/token/exchange/{tokenId}`	Exchange a one-time `tokenId` for the actual access token and patient context. The `tokenId` is consumed on read.	Yes
`GET`	`/api/workflow/auth/{integrationId}/token`	Request a Backend (Bulk) system token using the configured client credentials + provider username/password/officekey. No user interaction.	Yes
`POST`	`/api/workflow/auth/{integrationId}/token/refresh`	Refresh an expiring access token. Requires a previously issued refresh token (requested via `offline_access` scope).	Yes
`GET`	`/api/workflow/auth/{integrationId}/token/status/{tokenId}`	Check whether a `tokenId` is still valid and ready to exchange. Does not consume the token.	No

Examples

Copy-paste examples for the client-callable endpoints. Replace <your-ch-domain>, {integrationId}, {tokenId}, and YOUR_API_KEY with your actual values.

Token Exchange

Exchange a one-time tokenId for an access token + patient context after Standalone or Embed Launch flows.

curl

curl -X GET "https://<your-ch-domain>/api/workflow/auth/{integrationId}/token/exchange/{tokenId}" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

JavaScript (fetch)

const res = await fetch(
  `https://<your-ch-domain>/api/workflow/auth/${integrationId}/token/exchange/${tokenId}`,
  {
    headers: {
      "x-api-key": process.env.CH_API_KEY,
      "Accept": "application/json",
    },
  }
);
const { access_token, patient, scope, expires_in } = await res.json();

Backend Token (Bulk)

Request a system-level access token for server-to-server Bulk export flows.

curl

curl -X GET "https://<your-ch-domain>/api/workflow/auth/{integrationId}/token" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

JavaScript (fetch)

const res = await fetch(
  `https://<your-ch-domain>/api/workflow/auth/${integrationId}/token`,
  {
    headers: {
      "x-api-key": process.env.CH_API_KEY,
      "Accept": "application/json",
    },
  }
);
const { access_token, expires_in, scope } = await res.json();

Token Refresh

Refresh an access token before expiry. Only works if the original token was issued with offline_access.

curl

curl -X POST "https://<your-ch-domain>/api/workflow/auth/{integrationId}/token/refresh" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "YOUR_REFRESH_TOKEN"}'

JavaScript (fetch)

const res = await fetch(
  `https://<your-ch-domain>/api/workflow/auth/${integrationId}/token/refresh`,
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.CH_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ refresh_token: "YOUR_REFRESH_TOKEN" }),
  }
);
const { access_token, refresh_token, expires_in } = await res.json();

Response

{
  "body": {
    "access_token": "eyJhbGc...",
    "refresh_token": "dGhpcyBp...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "patient/*.read",
    "patient": "patient-id-if-applicable"
  },
  "message": "Token refreshed successfully",
  "timestamp": 1718000000000
}

Example Launch URL (registered in the AdvancedMD Developer Portal):

https://demo.ehrconnect.healthconnect.systems/api/workflow/auth/[your-integration-id]/launch

Replace the domain and integration ID with your actual values.

External Resources

AdvancedMD FHIR — Getting Started — Registration, app creation, and SMART authorization guide
AdvancedMD FHIR Developer Portal (Login)
AdvancedMD Developer Home
SMART App Launch Guide
FHIR Bulk Data Access (Flat FHIR)
FHIR R4 Specification

AdvancedMD

AdvancedMD (Global Payments)

AdvancedMD

AdvancedMD (Global Payments) FHIR R4 standalone-oauth backend-jwt smart-on-fhir

Overview

⚠

AdvancedMD FHIR is READ-ONLY

ℹ

Application Ownership

Supported Authentication Flows

Click a card to jump to its configuration section.

Standalone OAuth

Embed Launch

Backend (Bulk Export)

Key Features

FHIR resource search and read (READ-ONLY — no create/update/delete)
Bulk Data export ($export) via SMART Backend Services
Backend auth = RS384 JWT client assertion + username/password/officekey
Per-organization FHIR base URL (org_id in the path)
PKCE (S256) supported for authorization-code flows
Token refresh
Audit logging for all operations

Before You Begin

Prerequisites Checklist

✓ AdvancedMD developer account — Create one at the AdvancedMD FHIR Developer Portal (verify your email within 10 minutes of signup)
✓ Registered application(s) — Each app requests exactly one product: FHIR Single Patient API (for Standalone + Embed) and/or FHIR Bulk API (for Backend)
✓ InterOps authorization — File a "Have a FHIR Question" ticket so AdvancedMD authorizes your app's API access; you receive a Client key/secret
✓ Organization Base URL / org_id — AdvancedMD FHIR base URLs are per-organization (e.g. test orgs 174 / 175)
✓ Redirect URI configured — Registered in your AdvancedMD app (provided by ConnectHealth)
✓ For Backend (Bulk) — An RSA key pair (RS384) registered with AdvancedMD, plus the provider's username, password, and officekey

Create Your AdvancedMD Application

Follow these steps to register your AdvancedMD application. Your organization owns and manages this app on the AdvancedMD Developer Portal.

Create an AdvancedMD Developer Account

Go to the AdvancedMD FHIR Developer Portal → Sign In → Create account.

Provide your email, name, and password, and accept the Terms & Conditions
Verify your email within 10 minutes (the link expires; you can resend from the portal)
Your organization owns this account and all apps created under it

Create Your Application(s) — One Product Per App

Click your email (top right) → Apps → New app. Fill in the App name and Description, then request exactly one product per app:

For Standalone + Embed Launch: request FHIR Single Patient API
For Backend (Bulk export): request FHIR Bulk API

Do not request more than one product per app. Standalone/Embed and Backend therefore live in separate apps.

Get InterOps Authorization for Your App

Newly created apps are not usable until AdvancedMD's Interoperability team authorizes their API access. After creating your app(s):

Open AdvancedMD's InterOps Support page and submit a ticket using the "Have a FHIR Question" option
Reference each app name (and app ID) so the team can find and authorize it
Wait for confirmation that API access has been enabled

Retrieve Your Credentials and Org Base URL

Once authorized:

Open each app and copy its Client key (Client ID) and Client secret
Request the Organization Base URL / org_id for the practice you'll connect to (test orgs 174/175 are available in the sandbox; the production org list is downloadable as CSV / FHIR Bundle and is updated quarterly)
Register your ConnectHealth Redirect URI in the app (you get the exact value from ConnectHealth after creating your connection)

Configure in ConnectHealth

Now create your AdvancedMD connection in ConnectHealth:

In ConnectHealth, navigate to Connections and create a new connection
Select AdvancedMD as the EHR type
Select your workflow type — Standalone, Embed Launch, or Backend
Paste your Client ID / Client Secret, and the AdvancedMD endpoints + per-org Base URL (see the Configuration Reference below)
Copy the generated Redirect URL from ConnectHealth into your AdvancedMD app
Save your connection

Test with Sandbox Data

Sandbox Environment Setup

Sandbox Test Organizations

The portal exposes test Organization Base URLs. Each is a complete, per-organization FHIR R4 base URL.

Test Organization	Base URL
FHIR PRACTICE GROUP TEST	`https://providerapi.advancedmd.com/v1/r4/174`
FHIR PRACTICE GROUP TEST 2	`https://providerapi.advancedmd.com/v1/r4/175`

AdvancedMD OAuth + FHIR Endpoints

These are fixed for AdvancedMD. Enter them in ConnectHealth when configuring a connection (the Base URL is per-organization — append your org_id).

Purpose	URL
OAuth Authorization	`https://providerapi.advancedmd.com/v1/oauth2/authorize`
OAuth Token	`https://providerapi.advancedmd.com/v1/oauth2/token`
FHIR Base (R4, per-org)	`https://providerapi.advancedmd.com/v1/r4/{org_id}`
Bulk export kickoff	`https://providerapi.advancedmd.com/v1/r4/Group/{GroupId}/$export`

✅

The Base URL must include your organization id

Configuration Reference

ConnectHealth supports multiple workflow types for this integration. Choose the one that matches your use case.

Standalone OAuth

Field	Autofill	Required	Description
`Client ID`	No	Yes	Your application's Client key from the AdvancedMD Developer Portal.
`Client Secret`	No	Yes	Client secret for confidential clients (used for HTTP Basic auth). Keep this secure.
`Authorization URL`	No	Yes	`https://providerapi.advancedmd.com/v1/oauth2/authorize`
`Token URL`	No	Yes	`https://providerapi.advancedmd.com/v1/oauth2/token`
`FHIR Base URL`	No	Yes	Your per-org base URL: `https://providerapi.advancedmd.com/v1/r4/{org_id}`
`Scopes`	No	Yes	Space-separated scopes. The submodule auto-normalizes to include `openid` and `fhirUser`. Default: `openid fhirUser offline_access online_access patient/*.read`
`Redirect URL`	Yes	Yes	Your ConnectHealth callback URL, registered in your AdvancedMD app.

Setup Steps

Register an app requesting the FHIR Single Patient API product and get it authorized by InterOps.
Register your ConnectHealth redirect URI in the app.
Enter the AdvancedMD Authorization/Token URLs and your per-org FHIR Base URL in ConnectHealth.
Choose your scopes (openid and fhirUser are auto-added if missing).
Test by initiating a login — the user is redirected to AdvancedMD to authorize.

Backend (Bulk Export)

Field	Autofill	Required	Description
`Client ID`	No	Yes	Your Bulk app's Client key from the AdvancedMD Developer Portal.
`Token URL`	No	Yes	`https://providerapi.advancedmd.com/v1/oauth2/token`
`FHIR Base URL`	No	Yes	Org-less root for Bulk: `https://providerapi.advancedmd.com/v1/r4` (do not append `{org_id}` — AdvancedMD's Bulk `$export` kickoff lives at `/v1/r4/Group/{id}/$export`).
`JWKS Private Key` + `kid`	Generate	Yes	RS384 key pair. Generate it in ConnectHealth (or upload your own) and register the public key with AdvancedMD.
`Username`	No	Yes	Provider's AdvancedMD username, sent with the client_credentials request.
`Password`	No	Yes	Provider's AdvancedMD password.
`Office Key`	No	Yes	The AdvancedMD office key (unique client identifier) for the provider.
`Scopes`	No	Yes	System-level scope. AdvancedMD Bulk allows only `system/*.read`.

Setup Steps

Register an app requesting the FHIR Bulk API product and get it authorized by InterOps.
Generate an RS384 key pair in ConnectHealth and register the public key with AdvancedMD.
Enter the Token URL, per-org FHIR Base URL, and the provider's username / password / officekey.
Set the scope to system/*.read.
Test by requesting a backend token, then kick off a group $export and poll the status URL.

SMART on FHIR - Embed Launch

SMART on FHIR EHR launch flow (FHIR Single Patient API) for apps embedded within AdvancedMD. The app is launched from the EHR and receives patient context automatically via the launch parameter.

Field	Autofill	Required	Description
`Client ID`	No	Yes	Your application's Client key from the AdvancedMD Developer Portal.
`Client Secret`	No	No	Client secret for confidential clients (optional).

Setup Steps

Register an app requesting the FHIR Single Patient API product (the same app can serve Standalone + Embed).
Register your ConnectHealth Launch URL where AdvancedMD sends the iss and launch parameters.
Configure the Embed Launch workflow in ConnectHealth with the Client ID (and optional Client Secret).
Your app handles the tokenId returned by ConnectHealth and calls the token exchange endpoint to retrieve the access token.
Test by launching your app from within AdvancedMD.

How to Handle SMART Launch

AdvancedMD Initiates the Launch

When a clinician opens your app from within AdvancedMD, it calls your registered Launch URL:

GET https://<your-ch-domain>/api/workflow/auth/{integrationId}/launch?iss=...&launch=...

iss — AdvancedMD's FHIR base URL (e.g., https://providerapi.advancedmd.com/v1/r4/174)
launch — an opaque token carrying patient context

No action needed from you — this is the URL you registered in the AdvancedMD app.

ConnectHealth Completes OAuth and Returns a `tokenId`

Call Token Exchange to Retrieve the Access Token

Your app calls the Token Exchange endpoint with the tokenId. This endpoint requires the x-api-key header:

GET https://<your-ch-domain>/api/workflow/auth/{integrationId}/token/exchange/{tokenId}
Headers:
  x-api-key: <your-connecthealth-api-key>
  Accept: application/json

Response contains access_token, patient, scope, expires_in, and — if offline_access was requested — a refresh_token.

Call FHIR Using the Access Token (Read-Only)

Use the access_token as a Bearer token against your per-org FHIR base URL:

GET https://providerapi.advancedmd.com/v1/r4/{org_id}/Patient/{patient}
Headers:
  Authorization: Bearer {access_token}
  Accept: application/fhir+json

Remember: read/search only — AdvancedMD does not accept FHIR writes.

Refresh Before Expiry

Access tokens expire (typically in an hour). Before expiry, call the Token Refresh endpoint to obtain a new one without re-prompting the user. Like Token Exchange, this requires x-api-key:

POST https://<your-ch-domain>/api/workflow/auth/{integrationId}/token/refresh
Headers:
  x-api-key: <your-connecthealth-api-key>
  Content-Type: application/json

Body:
{
  "refresh_token": "<your-refresh-token>"
}

Refresh only works if offline_access was included in your requested scopes.

General Scopes

Scopes define the level of access your application requests. AdvancedMD scopes are based on USCDI v3. Choose them based on your workflow type and data needs.

Patient Scopes

Patient-level scopes grant access to the launched/authorized patient's data (Single Patient API).

Scope	Description
`patient/*.read`	Read all supported resource types for the patient (SMART v1 style)
`patient/*.rs`	Read and search all supported resource types for the patient (SMART v2 style)

User Scopes

User-level scopes grant access based on the permissions of the logged-in provider.

Scope	Description
`user/*.read`	Read all resource types the user has access to
`user/*.rs`	Read and search all resource types the user has access to

System Scopes (Bulk / Backend)

System-level scope for backend/server applications without a specific user context. Used with the Backend (Bulk Export) workflow.

Scope	Description
`system/*.read`	Read all resource types at the system level — the only scope AdvancedMD's Bulk API allows

Launch & Identity Scopes

Launch and OpenID Connect scopes. The submodule auto-adds openid and fhirUser if not present, and adds launch for EHR launch.

Scope	Description
`launch`	Required for EHR launch — receives the launch context from AdvancedMD (auto-added for embed)
`launch/patient`	Request patient context in a standalone launch
`openid`	Required for OpenID Connect — returns an ID token (auto-added)
`fhirUser`	Returns the FHIR resource URL of the authenticated user (auto-added)
`offline_access`	Request a refresh token for long-lived access
`online_access`	Request a session-scoped (online) refresh token

Use Cases

Choose the workflow type that best matches your application's needs. All AdvancedMD FHIR access is read-only.

Patient-Facing Applications

Scenario: A third-party app reads patient health data with the patient's explicit consent.

Recommended Workflow: Standalone OAuth (FHIR Single Patient API)

Best For: Patient portals, health tracking apps, care management tools

Recommended Scopes: openid fhirUser offline_access online_access patient/*.read launch/patient

Provider-Facing Applications

Scenario: A provider app reads data the logged-in clinician can access.

Recommended Workflow: Standalone OAuth or Embed Launch

Best For: Clinician dashboards, read-only chart viewers, decision-support tools

Recommended Scopes: openid fhirUser user/*.read

EHR-Embedded Applications

Scenario: An application launched from within AdvancedMD that receives patient context automatically.

Recommended Workflow: Embed Launch (SMART on FHIR)

Best For: In-context clinical viewers and read-only decision support

Recommended Scopes: launch openid fhirUser patient/*.read

Population / Bulk Data Export

Scenario: A server exports a group of patients' data without user interaction for analytics or reporting.

Recommended Workflow: Backend (Bulk Export) (FHIR Bulk API)

Best For: Population health analytics, reporting pipelines, data warehousing

Recommended Scopes: system/*.read

Get Your ConnectHealth API Key

Log in to the ConnectHealth Dashboard

Open your ConnectHealth instance (the URL where your deployment is hosted) and sign in with your account credentials.

Navigate to Settings → API Keys

From the left navigation, click Settings, then open the API Keys tab. If you have never generated a key before, the list will be empty.

Create a New API Key

Copy Your API Key

ConnectHealth saves your API key securely. You can view and copy the key value from Settings → API Keys at any time.

Use the Key in the `x-api-key` Header

Pass the key on every request to a protected endpoint using the header name x-api-key (lowercase, hyphenated). Example:

curl -X GET "https://<your-ch-domain>/api/workflow/auth/{integrationId}/token/exchange/{tokenId}" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

Endpoints requiring this header are listed in the API Endpoints section below.

API Endpoints

🔑

API Key Required on Token Endpoints

Token Exchange, Backend Token, and Token Refresh all require the x-api-key header. Create a key from Settings → API Keys before calling these endpoints.

Authentication Endpoints

Method	Endpoint	Description	API Key
`GET`	`/api/workflow/auth/{integrationId}/start`	Initiate OAuth flow for standalone launch. Typically hit from a browser; returns a redirect to AdvancedMD.	No
`GET`	`/api/workflow/auth/{integrationId}/callback`	OAuth redirect URI. Called by AdvancedMD after user authorization — not by your client. Exchanges the code for tokens and stores them, returning a one-time `tokenId`.	No
`GET`	`/api/workflow/auth/{integrationId}/launch`	SMART on FHIR EHR Launch URL. Called by AdvancedMD with `iss` and `launch` query params — not by your client.	No
`GET`	`/api/workflow/auth/{integrationId}/token/exchange/{tokenId}`	Exchange a one-time `tokenId` for the actual access token and patient context. The `tokenId` is consumed on read.	Yes
`GET`	`/api/workflow/auth/{integrationId}/token`	Request a Backend (Bulk) system token using the configured client credentials + provider username/password/officekey. No user interaction.	Yes
`POST`	`/api/workflow/auth/{integrationId}/token/refresh`	Refresh an expiring access token. Requires a previously issued refresh token (requested via `offline_access` scope).	Yes
`GET`	`/api/workflow/auth/{integrationId}/token/status/{tokenId}`	Check whether a `tokenId` is still valid and ready to exchange. Does not consume the token.	No

Examples

Copy-paste examples for the client-callable endpoints. Replace <your-ch-domain>, {integrationId}, {tokenId}, and YOUR_API_KEY with your actual values.

Token Exchange

Exchange a one-time tokenId for an access token + patient context after Standalone or Embed Launch flows.

curl

curl -X GET "https://<your-ch-domain>/api/workflow/auth/{integrationId}/token/exchange/{tokenId}" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

JavaScript (fetch)

const res = await fetch(
  `https://<your-ch-domain>/api/workflow/auth/${integrationId}/token/exchange/${tokenId}`,
  {
    headers: {
      "x-api-key": process.env.CH_API_KEY,
      "Accept": "application/json",
    },
  }
);
const { access_token, patient, scope, expires_in } = await res.json();

Backend Token (Bulk)

Request a system-level access token for server-to-server Bulk export flows.

curl

curl -X GET "https://<your-ch-domain>/api/workflow/auth/{integrationId}/token" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Accept: application/json"

JavaScript (fetch)

const res = await fetch(
  `https://<your-ch-domain>/api/workflow/auth/${integrationId}/token`,
  {
    headers: {
      "x-api-key": process.env.CH_API_KEY,
      "Accept": "application/json",
    },
  }
);
const { access_token, expires_in, scope } = await res.json();

Token Refresh

Refresh an access token before expiry. Only works if the original token was issued with offline_access.

curl

curl -X POST "https://<your-ch-domain>/api/workflow/auth/{integrationId}/token/refresh" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "YOUR_REFRESH_TOKEN"}'

JavaScript (fetch)

const res = await fetch(
  `https://<your-ch-domain>/api/workflow/auth/${integrationId}/token/refresh`,
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.CH_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ refresh_token: "YOUR_REFRESH_TOKEN" }),
  }
);
const { access_token, refresh_token, expires_in } = await res.json();

Response

{
  "body": {
    "access_token": "eyJhbGc...",
    "refresh_token": "dGhpcyBp...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "patient/*.read",
    "patient": "patient-id-if-applicable"
  },
  "message": "Token refreshed successfully",
  "timestamp": 1718000000000
}

Example Launch URL (registered in the AdvancedMD Developer Portal):

https://demo.ehrconnect.healthconnect.systems/api/workflow/auth/[your-integration-id]/launch

Replace the domain and integration ID with your actual values.

External Resources

AdvancedMD FHIR — Getting Started — Registration, app creation, and SMART authorization guide
AdvancedMD FHIR Developer Portal (Login)
AdvancedMD Developer Home
SMART App Launch Guide
FHIR Bulk Data Access (Flat FHIR)
FHIR R4 Specification

AdvancedMD

Overview

On This Page

Supported Authentication Flows

Standalone OAuth

Embed Launch

Backend (Bulk Export)

Key Features

Before You Begin

Prerequisites Checklist

Create Your AdvancedMD Application

Create an AdvancedMD Developer Account

Create Your Application(s) — One Product Per App

Get InterOps Authorization for Your App

Retrieve Your Credentials and Org Base URL

Configure in ConnectHealth

Test with Sandbox Data

Sandbox Environment Setup

Sandbox Test Organizations

AdvancedMD OAuth + FHIR Endpoints

Configuration Reference

Standalone OAuth

Setup Steps

Backend (Bulk Export)

Setup Steps

SMART on FHIR - Embed Launch

Setup Steps

How to Handle SMART Launch

AdvancedMD Initiates the Launch

ConnectHealth Completes OAuth and Returns a tokenId

Call Token Exchange to Retrieve the Access Token

Call FHIR Using the Access Token (Read-Only)

Refresh Before Expiry

General Scopes

Patient Scopes

User Scopes

System Scopes (Bulk / Backend)

Launch & Identity Scopes

Use Cases

Patient-Facing Applications

Provider-Facing Applications

EHR-Embedded Applications

Population / Bulk Data Export

Get Your ConnectHealth API Key

Log in to the ConnectHealth Dashboard

Navigate to Settings → API Keys

Create a New API Key

Copy Your API Key

Use the Key in the x-api-key Header

API Endpoints

Authentication Endpoints

Examples

Token Exchange

curl

JavaScript (fetch)

Backend Token (Bulk)

curl

JavaScript (fetch)

Token Refresh

curl

JavaScript (fetch)

Response

External Resources

AdvancedMD

Overview

On This Page

Supported Authentication Flows

Standalone OAuth

Embed Launch

Backend (Bulk Export)

Key Features

Before You Begin

Prerequisites Checklist

Create Your AdvancedMD Application

Create an AdvancedMD Developer Account

Create Your Application(s) — One Product Per App

Get InterOps Authorization for Your App

Retrieve Your Credentials and Org Base URL

Configure in ConnectHealth

Test with Sandbox Data

ConnectHealth Completes OAuth and Returns a `tokenId`

Use the Key in the `x-api-key` Header

ConnectHealth Completes OAuth and Returns a `tokenId`

Use the Key in the `x-api-key` Header