SMART on FHIR Explained: App Launch, Scopes and Backend Services

FHIR standardizes the data and the API. It does not, by itself, say how an app proves who it is, how a clinician authorizes it, or how it learns which patient is open in the EHR. Before SMART, every EHR answered those questions differently, so every app needed a custom integration per EHR. SMART App Launch, originally developed by the SMART Health IT project and now maintained as an HL7 implementation guide, standardizes those answers on top of OAuth 2.0 and OpenID Connect.

The result is the closest thing healthcare has to an app platform: a clinician-facing app that implements SMART correctly can, in principle, launch from any EHR that supports it, subject to each EHR's app registration and review process. In the US, ONC certification criteria for standardized API access require SMART support, which is why it is available across major platforms such as Epic and Oracle Health.

A SMART client starts by fetching the server's configuration document. It is served relative to the FHIR base URL and lists the authorization and token endpoints, supported scopes, PKCE methods and a list of capabilities.

GET /fhir/r4/.well-known/smart-configuration HTTP/1.1
Host: ehr.example.org
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "issuer": "https://auth.example.org",
  "authorization_endpoint": "https://auth.example.org/authorize",
  "token_endpoint": "https://auth.example.org/token",
  "jwks_uri": "https://auth.example.org/.well-known/jwks.json",
  "grant_types_supported": ["authorization_code", "client_credentials"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["private_key_jwt"],
  "scopes_supported": ["openid", "fhirUser", "launch", "launch/patient", "offline_access", "patient/*.rs"],
  "capabilities": [
    "launch-ehr",
    "launch-standalone",
    "client-public",
    "client-confidential-asymmetric",
    "context-ehr-patient",
    "context-standalone-patient",
    "permission-v2",
    "sso-openid-connect"
  ]
}

Read the capabilities array rather than assuming features. For example, permission-v2 indicates support for v2 scope syntax, and context-ehr-patient indicates that patient context is provided during EHR launch.

In both flows the app then performs an OAuth authorization code flow: it redirects the user to the authorization endpoint with its client_id, redirect_uri, requested scopes, a state value, an aud parameter equal to the FHIR base URL, and a PKCE code_challenge. After the user authenticates and approves, the app exchanges the returned code (plus the PKCE code_verifier) for an access token at the token endpoint.

Scopes describe the access the app wants: clinical data scopes such as patient/Condition.rs, identity scopes such as openid and fhirUser, context scopes such as launch/patient, and offline_access or online_access for refresh tokens. Request the minimum. Many EHRs let users approve a subset, so apps should handle receiving fewer scopes than requested. The FHIR security guide covers scope design in more depth.

• PKCE (Proof Key for Code Exchange) binds the authorization code to the client that requested it. SMART 2.x requires it with the S256 method for all apps.
• Public clients, such as browser-only or native apps, cannot keep a secret and rely on PKCE alone.
• Confidential clients authenticate at the token endpoint. SMART 2.x prefers asymmetric authentication with a signed JWT over a symmetric client secret.
• Validate the state parameter on return and only register exact redirect URIs.

Not every client has a human at the keyboard. Backend Services, included in SMART App Launch 2.x, covers system-to-system access such as nightly analytics loads or Bulk Data exports. The client uses the OAuth client_credentials grant, authenticates with a JWT signed by its registered private key, and requests system/ scopes. Because there is no user consent step, the authorization server relies on pre-registration and policy to decide what each client may access.

Backend services pair naturally with the Bulk Data Access implementation guide, which defines the asynchronous $export operation for population-level extracts. Architecture choices for supporting it are covered in the FHIR server architecture guide.

Most servers support both during the transition. Apps should read the server's capabilities, prefer v2 where available and degrade gracefully where not.

Most SMART projects that slip do so for reasons unrelated to the core OAuth flow. The issues below come up repeatedly when apps move from a sandbox to real EHR environments:

• Hard-coding endpoints. Each EHR customer has its own FHIR base URL and authorization server. Always derive endpoints from the iss value and the discovery document.
• Assuming every requested scope is granted. Inspect the scope value in the token response and disable features gracefully when access is narrower than requested.
• Ignoring token lifetimes. Access tokens are short-lived. Handle refresh, and handle refresh failure by restarting authorization rather than surfacing raw errors to clinicians.
• Embedding in iframes without testing. Some EHRs render apps in embedded browsers with cookie and storage restrictions that break session handling built for normal browsers.
• Skipping production data review. Sandbox data is clean; production data has missing codes, local code systems and unexpected profiles. Build defensively against the resources you actually receive.

For the broader delivery picture, including environments, testing and go-live, see the FHIR implementation guide.

CDS Hooks is a separate HL7 specification for invoking clinical decision support at defined points in the EHR workflow, such as patient-view when a chart opens or order-sign when orders are about to be signed. The EHR calls an external CDS service with context and, optionally, prefetched FHIR data; the service replies with cards containing information, suggestions or links.

The two are complementary. A card can include a link that launches a SMART app with the right context, so a lightweight hook can surface an alert and hand the clinician into a full app for deeper work. The CDS service accesses FHIR data using a token the EHR supplies, following the same OAuth principles.