Auth & SMART App Launch
SoFaaS™ implements the full SMART App Launch flow on your behalf. You declare what you need; the runtime handles the OAuth handshake and hands your app a token plus context.
SMART App Launch
SMART App Launch is the standard way third-party apps get launched from inside an EHR with patient context. SoFaaS™ implements both EHR launch (the clinician opens your app from inside Epic) and standalone launch (your app is opened first and then connects to an EHR session) — but EHR launch is the path that actually unblocks hospital deals, and it's where you should focus.
The flow, end to end:
- Clinician clicks your app in Epic.
- Epic redirects to the SoFaaS™ runtime with a launch token.
- SoFaaS™ exchanges the token for an OAuth access token, scoped to the patient and encounter.
- SoFaaS™ launches your app with the access token and resolved context.
- Your app calls SoFaaS™'s FHIR API. The runtime fronts Epic.
You don't implement steps 2–4. You implement step 5.
Scopes
You declare the SMART scopes your app needs in the SoFaaS™ console. The runtime requests them from Epic on your behalf during launch. Common scopes:
launch— required for EHR launch.patient/Patient.read— patient demographics.patient/Encounter.read— current encounter.patient/Observation.read— labs, vitals.patient/DocumentReference.write— write a clinical note back into the chart.openid fhirUser— identify the launching clinician.
Hospital security teams scrutinize scope lists. Request only what you need — every unnecessary scope adds a question to the security review. SoFaaS™'s review packet explains every scope you've declared, but a leaner list reviews faster.
Launch context
After launch, your app receives a context object containing (at minimum) the patient ID, encounter ID, and the launching user ID. The runtime resolves these against the EHR's identifiers; you address them as opaque IDs and pass them back to the SoFaaS™ FHIR API.
Don't try to parse Epic-specific identifiers. They're stable per-hospital but vary across hospitals. The whole point of the runtime is to keep your app portable across hospital deployments.
Tokens & refresh
Access tokens are short-lived (minutes to hours, depending on the EHR). SoFaaS™ handles refresh automatically for the duration of an active session. Your app sends the token back with each request; the runtime refreshes silently if needed.
For background workloads (cron jobs, async write-back queues), use the SoFaaS™ service token endpoint rather than trying to keep a user-launched access token alive. It's the right model for both compliance and reliability.
Common errors
- Invalid scope at launch. A scope you declared isn't permitted at this hospital. The hospital's Epic admin needs to grant it; SoFaaS™ surfaces this in the deployment dashboard.
- Missing encounter context. The clinician launched your app outside an encounter context (e.g. from a patient list). Handle gracefully — degrade to patient-only mode or prompt the user.
- Token expired. If you bypass the SoFaaS™ SDK and hold tokens manually, you'll see this. Use the SDK or implement the refresh contract documented in your deployment.
Stuck on auth in your hospital's Epic instance? Talk to us — 99% of "auth doesn't work" tickets are scope or context resolution problems we've seen before.