SMART on FHIR launch context selection describes how an application learns which patient, encounter, or other clinical boundary applies to a given session. The selection is not performed by the FHIR data store alone. In an EHR launch, the context originates from the user's current session inside the EHR or from a selection made at launch time [2]. In a standalone launch, the application asks the authorization server to acquire that context before tokens are issued [4]. Microsoft's Azure Health Data Services documentation states that identity providers authenticate users and issue tokens but do not have visibility into clinical workflows; the application must determine an appropriate patient context by prompting the user, selecting from a list, or retrieving it from another system [1]. Google's Cloud Healthcare API similarly leaves context creation to an external authorization server [3]. The practical question is therefore not which product selects context, but which component owns each step and what happens when the required context is absent.
Two Launch Patterns Produce Different Context Origins
The SMART App Launch specification defines two authorization patterns with different context-selection mechanics. In an EHR launch, a user-facing application connects to a FHIR server from within an existing EHR or patient portal session. The specification states that this pattern allows launch context such as a currently selected patient to be shared with the app, based on a user's session inside an EHR or other health data software, or based on a user's selection at launch time [2]. The context is therefore inherited from the host system's active clinical record rather than created by the app.
A standalone launch begins outside an EHR session, such as when a user taps an app icon on a mobile phone home screen [4]. In this flow, the app has no launch identifier at the point of authorization. The specification explains that standalone apps can declare launch context requirements by adding scopes such as launch/patient or launch/encounter to the authorization request, and the EHR's authorize endpoint will take care of acquiring the context [4]. This means the authorization server, not the FHIR resource server, becomes responsible for prompting a user or otherwise resolving the requested context before the app receives a token.
The Launch Parameter Is an Opaque Handle, Not a Patient Identifier
In an EHR launch, the launch URL carries two required parameters: iss, which identifies the EHR's FHIR endpoint, and launch, which is an opaque identifier for the specific launch and any EHR context associated with it [4]. The specification requires the app to echo the launch value back to the EHR at authorization time by passing a launch parameter [4]. The identifier itself does not encode a patient ID or encounter ID. Its meaning is resolved by the EHR authorization server when the app exchanges the authorization code for a token.
Microsoft's documentation describes this resolution step as occurring during token exchange, when the context is resolved and returned alongside the access token so that the application can make correctly scoped API calls [1]. The documentation states that this mechanism ensures the app operates within a clearly defined clinical boundary [1]. Because the launch handle is opaque, an application cannot derive clinical context by inspecting the URL. It must preserve the handle and present it during authorization, or the server has no basis for associating the app's request with the original EHR session.
Checklist for Tracing Context Through a Request
First, identify the launch pattern. An EHR launch supplies an opaque launch handle that must be echoed at authorization time [4]. A standalone launch instead declares launch/patient or launch/encounter as a requested scope and relies on the authorize endpoint to acquire context [4]. Second, confirm where the authorization server resolves context. Microsoft describes resolution during token exchange [1], while Google leaves token minting entirely to an external authorization server [3]. Third, verify that the selected context satisfies server-side checks: Google requires an existing Patient resource for patient-scoped requests and rejects mismatched resourceType and operation pairs [3]. Microsoft requires SMART clinical scopes in addition to the FHIR SMART User role [1].
Cloud FHIR Services Enforce Context but Do Not Create It
Azure Health Data Services and Google Cloud Healthcare API both describe enforcement boundaries that separate context creation from context consumption. Microsoft states that identity providers are responsible for authenticating users and issuing tokens, but they do not have visibility into clinical workflows [1]. The application must determine an appropriate patient context, either by prompting the user, selecting a patient from a list, or retrieving it from another system, and must include that context in the token used to call the FHIR service [1]. Microsoft describes an orchestration layer that acts as the bridge between the identity provider, the clinical system such as an EHR, and the FHIR service [1].
Google's documentation takes a similar position. FHIR store administrators create and configure an authorization server outside the Cloud Healthcare API that grants SMART authorization scopes and patient context [3]. Google states that the Cloud Healthcare API does not specify which launch workflow the client application uses and does not have specific requirements for how the authorization server mints the SMART JWT token; an application might be registered for a subset of scopes, or it might present a patient selection widget to set the patient context [3]. Enforcement occurs later: if a patient role is provided, a patient context must be supplied, and the Patient resource must already exist in the FHIR store or exist after the request is made, otherwise the request is rejected [3].
Scope and Context Are Separate but Interdependent Requirements
SMART scopes define delegated permissions, while launch context defines the clinical boundary for those permissions. The specification gives the example of user/Encounter.rs, which allows reading and searching Encounters accessible to the authorizing user, and notes that user-facing apps can also receive launch context to indicate details about the current patient and other aspects of a user's EHR session [2]. A token can therefore carry a valid clinical scope but still lack the patient context required to make a patient-scoped request meaningful.
Microsoft's documentation makes this interdependence explicit. A principal that holds the FHIR SMART User role and presents a token without SMART clinical scopes gets no data access at all, including read [1]. The SMART user role by itself does not grant access to data; each request is further limited by the fhirUser context and the SMART clinical scopes in the access token [1]. Google adds a resource-level constraint: when creating, reading, updating, or deleting a resource, the resourceType and type of operation must match, otherwise the request is rejected [3]. These checks operate after context selection, but they fail predictably when the selected context does not align with the requested resource type.
A Validation Scenario for Context Selection Boundaries
A useful hypothetical validation scenario would separate the two launch patterns and test where context is acquired. In the first case, a test patient exists in the FHIR store, and a SMART client launches from an EHR session with that patient active. The app receives an iss and launch parameter, echoes the launch value during authorization, and then confirms that the token exchange returns a patient context matching the active record [4][1]. In the second case, the same client launches standalone and requests launch/patient without any prior EHR session [4]. The expected behavior is that the authorization server prompts for or otherwise acquires a patient before issuing the token.
This scenario is a suggestion for isolating context-selection behavior, not a report of independent testing. Microsoft's documentation recommends a test patient in the FHIR store and a SMART client application or the SmartLauncher sample for validation [1]. Google's documentation notes that if no authorization server configures SMART JWT tokens, the Apigee-based HealthAPIx accelerator can be used to set up an authentication server that signs JWT tokens [3]. Neither source establishes that a particular implementation will behave identically across vendors, and the scenario does not measure clinical outcomes or compliance.
Sources & references
- SMART on FHIR in Azure Health Data Services | Microsoft Learn · learn.microsoft.com
- Overview - SMART App Launch v2.2.0 · hl7.org
- Connect to applications using SMART on FHIR | Cloud Healthcare API | Google Cloud Documentation · docs.cloud.google.com
- App Launch: Launch and Authorization - SMART App Launch v2.2.0 · www.hl7.org
- Standards and IGs Index and Resources | CMS · www.cms.gov