The Startup MDVisit Website →
← Back to blog

Developers: Launch SMART on FHIR Apps Without Weeks of Vendor Review

September 6, 2026
Developers: Launch SMART on FHIR Apps Without Weeks of Vendor Review

SMART on FHIR apps are third-party applications that use the SMART App Launch specification and OAuth2/OpenID Connect on top of the FHIR API to securely connect with electronic health record systems. This guide covers the specs to read, the authorization patterns to implement, the discovery metadata your client needs to parse, the tooling and sandboxes worth testing against, and a deployment checklist for moving from prototype to live EHR access.

TL;DR:

  • Developers must carefully check the FHIR version an EHR sandbox runs to avoid integration failures caused by mismatched resource shapes and search parameters.
  • Building a capability matrix for each EHR support plan helps prevent late-stage surprises by tracking grant types, scopes, client authentication, and introspection support upfront.
  • Implementing the correct authorization pattern depends on whether the app is user-facing (using OAuth2 with PKCE) or backend (using signed JWTs with asymmetric authentication), with scope selection crucial for approval.
  • Reading the server’s well-known smart configuration document before requesting scopes ensures compatibility and reduces failed token exchanges.
  • Engaging clinical and compliance stakeholders early through clinical leadership advisory support significantly accelerates the move from prototype to production deployment.

Table of Contents

What Is Smart on FHIR and How Does It Relate to FHIR?

FHIR defines the data model. It tells you how a Patient, Observation, or MedicationRequest resource is structured and how to read or write it over REST. SMART on FHIR is the layer sitting on top of that model, handling app launch, authorization, and the context an app needs to know which patient or encounter it's working with.

Three roles matter here: the client app you're building, the EHR acting as the resource server holding clinical data, and an authorization server issuing tokens (sometimes bundled with the EHR, sometimes separate). The SMART App Launch specification governs this handshake, while SMART Health IT's documentation walks through practical implementation.

Two things to keep straight:

  • FHIR answers "what does the data look like and how do I query it?"
  • SMART answers "how does my app get permission to see that data, and whose data is it?"

Confusing the two is the most common early mistake among developers new to FHIR healthcare applications.

Core Components: App Launch, Backend Services, and US Core Obligations

SMART App Launch splits into two patterns you'll implement differently depending on who's using the app. User-facing apps (launched from inside an EHR session or standalone by a clinician or patient) follow an interactive OAuth2 authorization code flow. Backend services, by contrast, run without a human present, authenticating with signed JWTs to pull data on a schedule or in response to events.

US Core adds a layer most developers underestimate: it documents which SMART obligations a certified server must meet, including which scopes it has to support and whether it must expose token introspection. That matters because your app's capabilities are bounded by what the server actually implements, not just what the spec allows.

Key components to map out before writing code:

  • User-facing launch: interactive, browser-based, requires redirect handling
  • Backend services: server-to-server, JWT-based, no user interaction
  • US Core capability obligations: which scopes and introspection features a certified server must expose
  • Version compatibility: confirm whether your target EHR runs FHIR R4 or R4B, since resource shapes and some search parameters differ

Spec-version mismatches cause more integration failures than authorization bugs. Check the FHIR version an EHR sandbox actually runs before assuming R4 behavior everywhere.

Which Authorization Patterns Should Developers Implement?

Authorization code flow with PKCE is the standard for public, user-facing apps, meaning anything running in a browser or mobile client where you can't safely store a secret. For confidential clients, especially backend services, the SMART App Launch IG's own guidance favors asymmetric authentication using a private key JWT over a shared client secret, since it avoids transmitting a secret at all and aligns with how most EHR vendors certify backend integrations.

OpenID Connect layers identity on top of authorization. When your app needs to know who's logged in (not just what data it can access), request the openid and fhirUser scopes to get a resolvable reference to the practitioner or patient.

Scope choice depends on session length:

  • Use online_access for apps that only need a token during an active user session
  • Use offline_access when your app needs a refresh token to operate after the user has logged off, such as a background sync job
  • Reserve system-level scopes for backend services with no user context at all

Pro Tip: Request the narrowest scope set that satisfies your use case. Broad scope requests are the single most common reason EHR reviewers send integration requests back for revision.

How Do Apps Discover Server Capabilities Before Launch?

Every SMART-conformant server publishes a /.well-known/smart-configuration JSON document, and reading it first, before requesting any scope, saves hours of failed token exchanges. That document lists the authorization_endpoint, token_endpoint, jwks_uri, scopes_supported, and a capabilities array describing what the server actually implements.

Not every EHR implements the same optional capabilities, and US Core requires certified servers to publish scopes_supported and support token introspection, but the exact fields returned still vary by vendor. Build your client defensively:

  • Parse scopes_supported and only request scopes the server actually lists
  • Check capabilities for launch context support before assuming launch/patient will work
  • Use the jwks_uri for key rotation rather than hardcoding public keys
  • Fall back gracefully when a server omits a recommended but non-mandatory field

Treat the capabilities document as a contract, not a formality. Skipping it is the fastest way to build an app that works against one EHR sandbox and fails against every other.

What Tools and Sandboxes Should Developers Use?

You don't need to build authorization logic from scratch. Client and server libraries exist across most major languages: JavaScript and TypeScript developers typically reach for the fhirclient library, Python developers use fhirclient or fhir.resources, and Java and .NET teams have SDK options tied to their existing FHIR server stacks.

For testing, three tools cover most needs, including those documented in the Use SMART on FHIR proxy - Microsoft Docs:

  • SMART App Launcher: simulates an EHR launch context so you can test your OAuth flow without EHR sandbox access
  • Logica Sandbox: a hosted FHIR server for realistic data interactions during development
  • SMART App Gallery: a catalog of production and sample apps (growth-chart trackers, blood pressure centile calculators, clinical decision tools) organized by specialty and EHR support, worth studying before you design your own UX

If a gallery app solves a problem close to yours, forking its approach beats reinventing the launch and token logic yourself. SMART Health IT's tutorials and sample apps are built specifically for this kind of reuse.

EHR Launch, Standalone Launch, or Backend Service: Which Flow Applies?

Three launch models cover almost every real-world integration, and each needs a slightly different implementation approach.

  1. EHR-initiated launch: The EHR opens your app inside a clinician's session and passes a launch parameter plus an iss value identifying the FHIR server. Your app exchanges that launch parameter during authorization to receive patient and encounter context automatically, so you never build a patient-picker for this flow.
  2. Standalone launch: Your app initiates the flow itself, typically from outside an EHR session (a patient portal or a clinician's own bookmark). Since there's no inherited context, your app must handle patient selection in its own UI, often through a patient/*.read scope request that resolves after login.
  3. Backend service: No human triggers the launch. Your app authenticates with a signed JWT, requests system-level scopes, and runs as a long-lived job, useful for bulk data exports or scheduled sync tasks against sources like CMS's Blue Button and BCDA endpoints.

Test each scenario separately in a sandbox before assuming your logic generalizes across all three.

What Belongs on Your Pre-Launch Deployment Checklist?

Getting production access from an EHR vendor takes weeks, not days, and most delays trace back to incomplete client registration rather than code defects.

  1. Prepare registration details early: redirect URIs, jwks_uri, app logo, and a working contact email. Vendors reject incomplete submissions outright.
  2. Apply least privilege to scopes: request only the resource types and access levels your app actually uses, and set refresh-token lifetimes as short as your use case allows.
  3. Validate token handling: confirm your app checks token expiry, rotates keys against the published jwks_uri, and supports introspection or revocation if the EHR requires it.
  4. Run full sandbox tests: verify the patient context banner displays correctly, confirm your app behaves when a session times out, and check that failed launches produce a clear error rather than a silent hang.

Pro Tip: Build a capability matrix across every EHR you plan to support, tracking grant types, client-auth methods, supported scopes, and introspection availability. Teams that skip this step almost always discover a mismatch after they've already started coding against a second vendor. Organizations managing multiple EHR relationships often formalize this inside a broader clinical messaging framework to avoid late-stage surprises. Teams deploying to production environments should also review HITRUST versus SOC 2 requirements before committing to a security posture.

When Does SMART Integration Need Outside Advisory Help?

Building SMART on FHIR apps is a solvable engineering problem. Getting an EHR vendor's clinical and compliance stakeholders to approve production access is a different challenge entirely, one where technical correctness alone doesn't move the timeline. Decide based on three factors: how much compliance risk your app carries, how many EHR vendor variants you must support, and how fast you need to reach a health system's production environment.

Fractional clinical leadership tends to compress this timeline because it puts a credentialed voice in front of a health system's medical informatics committee, someone who can speak both languages. A typical engagement moves through a diagnostic review of your current integration posture, a roadmap prioritizing which EHR relationships to pursue first, and hands-on support through go-live.

The Overlooked Cost in Most SMART on FHIR Strategy

Most SMART on FHIR strategy discussions focus almost entirely on the technical build, and that focus is misplaced. The specs are stable, the tooling is mature, and a competent engineering team can get a working prototype against a sandbox in days. What actually stalls these projects is the assumption that technical conformance equals deployment readiness.

The Overlooked Cost in Most SMART on FHIR Strategy — overview diagram

It doesn't. An app that perfectly implements the SMART App Launch IG can still sit in vendor review for months because nobody addressed how a health system's clinical informatics committee will evaluate patient safety, workflow disruption, or data governance. That's a stakeholder problem, not a code problem, and most engineering-led teams don't budget time for it.

The conventional advice tells teams to "read the spec and build to it." That's necessary but insufficient. The teams that get to production fastest treat clinical and compliance alignment as a parallel work stream from day one, not a phase that starts after the code is done. If you take one thing from this guide, take that: your capability matrix should include your health system's approval process, not just your EHR vendor's technical requirements.

— Paul Bergeron MD, MBA

How The StartupMD Supports Your Smart on FHIR Rollout

The StartupMD gives healthcare SaaS teams something a pure engineering vendor can't: a physician-led advisory voice that speaks directly to the clinical and compliance stakeholders standing between your working prototype and a signed EHR agreement.

The StartupMD

Founded by Paul Bergeron, MD, MBA, The StartupMD provides fractional Chief Medical Officer services, clinical strategy development, and integration roadmaps built specifically for healthcare SaaS companies navigating EHR partnerships. Rather than hiring a full-time executive before you've proven product-market fit, engage fractional clinical leadership only for the stretch where it matters most: readiness review, stakeholder alignment, and go-live support.

If your SMART on FHIR app is technically ready but stalled on health-system approval, a technical readiness review is the logical next step. Start by reviewing The StartupMD's go-to-market services to see how a fractional CMO engagement fits into your launch timeline.

Sources