What is SMART on FHIR?

SMART on FHIR is a standards-based way for apps to securely connect to healthcare data in EHRs and other FHIR servers. It combines HL7 FHIR (the data model and REST API) with a profile of OAuth 2.0 and OpenID Connect for authorization, so users can safely launch apps and share only the minimum necessary data.

How it works (at a glance)

Discovery: The EHR/FHIR server publishes its OAuth/OpenID endpoints and capabilities at /.well-known/smart-configuration (and often /.well-known/openid-configuration).
App launch:
- EHR launch: A user launches the app from the EHR. The EHR passes a short-lived launch code that encodes context (e.g., patient and encounter).
- Standalone launch: An app starts outside the EHR and requests context via scopes.
Authorization: The app sends the user to the authorization server with scopes such as launch/patient, openid, fhirUser, and granular data scopes like patient/Observation.read. Public apps use PKCE; confidential apps may also use a client secret.
Token exchange: After the user grants access, the app exchanges the code for an access token (and optionally a refresh token) and receives an ID token containing claims like fhirUser.
API access: The app calls the FHIR REST API (JSON over HTTP) with Authorization: Bearer <token> to read/write resources permitted by the granted scopes.

Example (simplified)

Authorization request:

GET https://auth.example.org/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
  &scope=launch%2Fpatient%20openid%20fhirUser%20patient%2FObservation.read%20offline_access
  &aud=https%3A%2F%2Ffhir.example.org
  &state=opaque-state
  &code_challenge=...&code_challenge_method=S256
  &launch=...  // only for EHR launch

FHIR API call:

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://fhir.example.org/Patient/$PATIENT_ID

Key concepts

FHIR: A resource-based standard (e.g., Patient, Encounter, Observation) with a RESTful API.
SMART: A security and launch framework over OAuth 2.0/OIDC that defines scopes, launch context, and required metadata.
Scopes: Granular permissions such as patient/Condition.read, user/Observation.write, system/*.read, plus identity/context scopes like openid, fhirUser, profile, launch/patient, and launch/encounter.
Launch context: App gets identifiers (e.g., patient, encounter, need-to-know) via EHR-provided launch parameter or via scopes for standalone.
Identity: With openid + fhirUser, the ID token identifies the current practitioner or patient and may reference a FHIR resource.
PKCE: Proof Key for Code Exchange; required for public/native and often for browser-based apps.

Why it matters

Interoperability: Works across EHR vendors and FHIR servers that implement the spec.
Security by design: OAuth/OIDC, least-privilege scopes, and auditable consent flows.
Faster app delivery: Reuse a common launch model instead of custom integrations.
Patient- and clinician-centered: Apps run in-context of the current patient/encounter.

Common use cases