Authentication

The ModMed Certified (ONC) FHIR API uses OAuth 2.0 with the SMART App Launch framework to authorize requests. Your application obtains an access token, then includes it as a Bearer token on every FHIR call. Which flow you use depends on the kind of application you're building — see App Types below.

Endpoints

The same token endpoint serves both flows, but client authentication differs by grant type: authorization_code/refresh_token use client_secret_post (send client_id/client_secret in the body); client_credentials (Bulk FHIR) uses private_key_jwt instead — no client_secret at all. See Client Credentials below. PKCE (S256) is supported and recommended for user-facing apps.

App Types

Before registering, decide what type of application you're building — it determines how users authenticate and which scopes you request.

• Bulk FHIR (system / background) — If you're working with a practice and need access to their providers' and patients' clinical data at the practice level, build a Bulk FHIR application. A practice Admin adds your ClientId to their practice once, and your application accesses data as needed using the client_credentials flow, authenticated with a signed JWT (private_key_jwt) — not a client_secret. No per-user authentication.
• Patient apps — Require a Patient at the practice (with valid Patient Portal username/password) to authenticate. After the first Standalone authentication, a link is placed inside the patient portal for repeated access and for the patient to manage or disable access.
• Provider apps — Require a Provider at the practice to authenticate with the same credentials they use for the EHR. After authenticating, a link is placed inside their EHR instance (location varies by scope) to launch your app from within the EHR.
• Patient and Provider apps — Handle authentication for both patients and providers.

For all Patient and Provider app types, the vendor must provide the initial Standalone authentication mechanism. Once a user authenticates via the Standalone flow, an in-context EHR Launch link is placed in their UI for ongoing use.

Authorization flows

Authorization Code (with PKCE) — Patient & Provider apps

1. Redirect the user's browser to the authorization endpoint with: response_type=code, client_id, redirect_uri, scope (space-separated), state, aud (the FHIR base URL above), and code_challenge + code_challenge_method=S256.
2. The user authenticates — Patient Portal credentials for patient apps, EHR credentials for provider apps. For EHR Launch, the app is started from within EMA and receives a launch parameter (include the launch scope).
3. The server redirects back to your redirect_uri with a code and your state.
4. Exchange the code at the token endpoint: grant_type=authorization_code, code, redirect_uri, code_verifier, client_id, client_secret.
5. You receive an access_token (plus an id_token when openid is requested, and a refresh_token when online_access/offline_access is granted). Send the access token as Authorization: Bearer <token> on FHIR calls.

Client Credentials — Bulk FHIR / background apps

No browser, no user interaction, and no client_secret. Your client is registered with a JWKS containing your public key; each token request authenticates with a client_assertion — a JWT signed with your matching private key — instead of a shared secret (private_key_jwt).

POST to the token endpoint with:

• grant_type=client_credentials
• client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
• client_assertion — a JWT signed with your private key, with claims iss/sub = your client_id, aud = this token endpoint URL, plus jti/iat/exp (a short expiry — 5 minutes is typical). Confirmed working signing algorithm: ES384.
• scope — required on this grant (space-separated system/*.rs scopes); it isn't implied the way it can be on the other grants.

Note there's no client_id field in the body either — the client is identified via the client_assertion JWT's iss/sub claims. Use the returned access_token as a Bearer token.

Scopes

Request only the scopes your application needs. Scopes fall into four groups.

Context scopes — control what gets put in the token

Identity scopes — control what you know about the logged-in user

Session scopes — control token lifetime

Resource scopes — control what FHIR data you can read

Recommended scopes by app type

Register

Haven't registered yet? See Become a ModMed Certified FHIR API Vendor to choose your app type and configure your application.