In short
- SMART on FHIR app launch is an OAuth 2.0 authorization code flow, defined in HL7's SMART App Launch guide, through which an app discovers an EHR's endpoints, asks for scopes, and receives an access token plus launch context such as the current patient.
- In an EHR launch the EHR opens your app with iss and launch parameters, and in a standalone launch your app starts on its own and asks for context through scopes such as launch/patient; both require PKCE with S256.
- Scopes such as patient/Observation.rs say what the app may do, the server may grant fewer than you asked for, and backend apps with no user use a separate client credentials flow with system scopes.
SMART on FHIR app launch is the OAuth 2.0 authorization code flow an app uses to get permission to call an EHR's FHIR API. The app discovers the EHR's authorization endpoints, sends the user to sign in and approve access, and exchanges a short-lived code for an access token. The token response also carries launch context, such as which patient is open, so the app knows whose data to load.
This explainer is for engineers and technical product managers building apps that run against Epic, Oracle Health, athenahealth or any EHR certified to ONC's API criterion. It follows HL7's SMART App Launch guide, version 2.2.0, step by step. ONC's §170.315(g)(10) criterion names SMART App Launch 2.0.0 as the base version and lists 2.2.0 among the approved later versions, which is why the flow works much the same across certified EHRs.
What is the difference between an EHR launch and a standalone launch?
In an EHR launch, the user is already in the EHR and opens your app from there. The EHR calls your registered launch URL with two parameters: iss, the EHR's FHIR endpoint, and launch, an opaque identifier for the current context. Your app sends the launch value back in its authorization request and asks for the launch scope. Clinician tools that open beside the chart work this way.
In a standalone launch, the user starts in your app, so there is no launch parameter. Your app asks for the context it needs through scopes such as launch/patient, and the EHR's authorization server collects that context, for example by letting the user pick a patient or by using the patient who signed in. Patient apps and portals usually work this way. Epic describes standalone launch as the option for apps that use OAuth 2.0 for sign-in but do not need to be launched from Epic.
How does your app find the EHR's endpoints?
Through discovery. The app sends an HTTP GET to the FHIR base URL plus .well-known/smart-configuration, with an Accept header that includes application/json. The response includes the authorization_endpoint and the token_endpoint, along with the capabilities the server supports. Do this at runtime for each server rather than hard-coding URLs, because each organization has its own endpoints.
What goes into the authorization request?
The app redirects the browser to the authorization endpoint with these parameters:
- response_type, fixed to code.
- client_id, the identifier you received at registration.
- redirect_uri, which must match one you registered in advance.
- scope, the access you are asking for, such as patient/Observation.rs, plus openid fhirUser if you need the user's identity and launch or launch/patient for context.
- state, an unpredictable value with at least 122 bits of entropy that the app must validate when the user returns.
- aud, the FHIR server's URL. In an EHR launch it matches iss.
- code_challenge and code_challenge_method for PKCE. The method must be S256.
- launch, required in an EHR launch and absent in a standalone launch.
GET {authorization_endpoint}?response_type=code
&client_id=my-app
&redirect_uri=https://app.example.com/callback
&scope=launch openid fhirUser patient/Patient.rs patient/Observation.rs
&state=<random value>
&aud=<FHIR base URL from iss>
&launch=<value from the EHR>
&code_challenge=<S256 hash of the verifier>
&code_challenge_method=S256The guide says SMART servers shall support S256 and shall not support the plain method, so PKCE is mandatory. After the user signs in and approves, the EHR redirects back with code and state. Authorization codes are short-lived, typically about one minute, so exchange them right away.
What comes back in the token response?
The app posts the code, the redirect_uri, the PKCE code_verifier and grant_type=authorization_code to the token endpoint. A public client, such as a browser-only app, includes its client_id. A confidential client authenticates instead, and the guide recommends asymmetric authentication where available.
- access_token and token_type, which is Bearer. Both are required.
- scope, also required, and it may differ from what you asked for.
- expires_in, recommended, in seconds.
- id_token, when you asked for openid and fhirUser.
- refresh_token, optional, only when online_access or offline_access was granted and the server allows it.
- patient and other context, such as encounter, when the app was launched with that context.
The app then calls the FHIR API with the header Authorization: Bearer followed by the token. The resource server must validate the token, check it has not expired, and check that it was issued for that server.
How do SMART scopes work?
A scope has three parts: a context, a resource type and permissions. The context is patient for one patient's data, user for data the signed-in user can access, or system for backend clients with no user. Permissions use the letters c, r, u, d and s for create, read, update, delete and search, in that order. So patient/Observation.rs means read and search the current patient's observations, and user/Observation.crus would add create and update.
Version 1 scopes used .read and .write. The guide maps .read to .rs, .write to .cud and .* to .cruds. Servers that support the old syntax should advertise permission-v1 in their configuration, and Epic's documentation notes that SMART v2 scopes use the CRUDS syntax.
Scopes can also carry search restrictions. The guide's example appends a category query, the observation-category code system and the code laboratory, to patient/Observation.rs, which limits the token to lab results. The guide lists search modifiers, chaining and _filter in scopes as experimental. Use them when a feature needs only one kind of data.
The scopes chapter also warns that the scopes the server grants may differ from the scopes the client requested. The guide recommends that clients examine the granted scopes and respond accordingly. Build your app to turn off features whose scopes were not granted, instead of failing on the first call.
How do refresh tokens and offline access work?
The offline_access scope asks for a refresh token that works whether or not the user is online. The online_access scope asks for one that works only while the user is still online. To refresh, the app posts grant_type=refresh_token and the refresh token, optionally with a narrower scope. The guide says a refresh token is bound to the same client_id.
Certified EHRs add rules on top. Under §170.315(g)(10), on first connection they must issue a refresh token valid for at least three months to confidential apps and to native apps that can secure one. They must also revoke an app's access within one hour of a patient's request. Your app needs a clear path for both: staying connected for months, and reconnecting cleanly after revocation.
What about apps with no user?
Backend Services covers them. A backend client, such as a data pipeline or a monitoring service, must be a confidential client registered with the server in advance. It authenticates with a signed, one-time-use JWT instead of a shared secret, uses the client_credentials grant and requests system scopes. The guide says expires_in should not exceed 300 seconds and that refresh tokens should not be issued, so the client simply requests a new token when it needs one.
Key management becomes part of deployment. Epic's documentation, for example, says you upload non-production and production public keys for each customer, that a re-uploaded key needs time to sync, and that a cloud-hosted app may reuse public keys across customers.
What mistakes break SMART launches most often?
- Hard-coding endpoints instead of reading .well-known/smart-configuration for each server.
- Skipping state validation or PKCE in development and forgetting to add them back.
- A redirect_uri that differs from the registered one by a slash or a port.
- Assuming every requested scope was granted.
- Storing tokens in the browser for an app that could keep them on a server.
- Not handling an expired or revoked token, so the user sees an error instead of a sign-in prompt.
- Asking for broad scopes, which slows every health system's review.
We have shipped Epic and athenahealth integrations, and for any vendor platform we work from the vendor's documentation and sandbox. If you are building a SMART on FHIR app and want a second pair of eyes on the launch, scopes and token handling, talk to one of our engineers. Our free five-day technical audit ends with a written report.