Planning My First SMART on FHIR Integration

SMART on FHIR is often summarized as "OAuth for healthcare APIs." That is directionally useful, but too small for planning a real integration. A working product must connect authorization to clinical context, map its own data to FHIR resources, cope with differences between servers, and make failures understandable to users who are trying to complete healthcare work.

This work is part of a patient-history platform with patient and clinic-admin applications, more than 150 conditional intake questions, and document capture. I am still early in the integration, so this article records the planning decisions and questions rather than presenting years of FHIR specialization.

FHIR and SMART solve different parts of the problem

FHIR defines healthcare data resources and API interactions. SMART App Launch defines foundational authorization and integration patterns based on OAuth 2.0 for applications connecting to FHIR-based systems. The current published SMART App Launch guide is version 2.2.0 and is based on FHIR R4.

A user-facing app can launch from an EHR and receive context such as the patient currently selected in that session. A standalone app can request patient selection during launch. Backend services use a different pattern for system-to-system access without a user directly involved.

Primary reference: HL7 SMART App Launch implementation guide.

Choose the launch model before designing the workflow

EHR launch

The application opens from within an EHR session. The launch request can carry context connected to the current user, patient, or encounter. This can make the experience feel native to the clinical workflow, but it also ties product behavior to what context that EHR supplies.

Standalone launch

The application begins outside the EHR and directs the user through authorization and, when supported, patient selection. This works for products with their own entry point but requires careful handling of organization, endpoint, identity, and selected-patient state.

Backend service

An automated service accesses FHIR resources without an interactive user launch. The authorization, client authentication, data boundaries, and operational controls differ from a user-facing application.

Request the access the product actually needs

SMART scopes communicate requested access to FHIR resources, context, and identity. The current scope syntax can distinguish actions such as create, read, update, delete, and search. A patient-level read and search request for observations, for example, can be represented as patient/Observation.rs.

The authorization server can grant something different from what the client requested, and the underlying EHR permissions still apply. An app therefore needs to inspect the granted scopes and handle missing permissions, filtered results, and rejected operations rather than assuming authorization succeeded exactly as requested.

Wildcard scopes are convenient but broad. The HL7 guide recommends requesting only the scopes and permissions required for the application to function. See HL7 guidance on scopes and launch context.

Define resource mapping and source-of-truth behavior

A product concept rarely maps perfectly to one FHIR resource. A patient-history workflow may involve Patient, Questionnaire, QuestionnaireResponse, Condition, AllergyIntolerance, Medication-related resources, Observation, DocumentReference, and Encounter context. The correct mapping depends on the workflow and the server's supported profiles.

For every mapped field, decide:

• Which FHIR resource and profile represent the concept?
• Is the application reading, writing, or doing both?
• Which system is authoritative when values differ?
• How are identifiers, terminology, units, and references normalized?
• What happens when the destination does not support the expected field or operation?
• How will partial success and duplicate writes be detected?

Design for EHR variation

FHIR creates a common model, not identical implementations. Servers can expose different versions, profiles, search behavior, scopes, resource coverage, extensions, write permissions, and operational limits. Discovery and capability metadata help, but a production integration still needs a compatibility layer and environment-specific testing.

A useful integration plan identifies the first supported EHR environment, the exact workflow and resources required there, and the variation the product is willing to absorb. "Works with FHIR" is not a testable acceptance criterion.

What I would establish before implementation

1. Define the user, launch model, selected-patient behavior, and clinical workflow.
2. Inventory required read, search, create, and update operations by FHIR resource.
3. Choose minimum scopes and define behavior for partially granted access.
4. Map product data to resources, profiles, terminology, identifiers, and references.
5. Document source-of-truth rules, duplicate prevention, and write-back semantics.
6. Test authorization expiry, missing context, filtered results, rate limits, and partial failures.
7. Design logs and support tools that help diagnose integration issues without unnecessarily exposing PHI.