Implement SMART EHR launch and extract launch context (patient, encounter, user)

domain: smart-on-fhir · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗

Steps

  1. The EHR initiates the launch by redirecting to your app's launch URL with parameters iss (FHIR base URL) and launch (opaque launch token).
  2. Fetch [iss]/.well-known/smart-configuration to discover the authorization endpoint.
  3. Redirect to the authorization endpoint including the launch parameter and scope containing 'launch' (not 'launch/patient'); this tells the server the launch token carries context.
  4. After authorization code exchange, the token response includes context claims: patient, encounter, and/or user as top-level fields alongside access_token.
  5. Use the patient value directly as the patient ID for FHIR queries; it is the logical ID of the FHIR Patient resource in context.
  6. Decode the id_token (a JWT) to obtain the fhirUser claim, which is the relative URL of the Practitioner or Patient resource representing the logged-in user.

Known gotchas

Related routes

Implement SMART App Launch v2 EHR launch flow including fhirContext extraction for multi-resource launch context
hl7.org · 6 steps · unrated
Implement SMART App Launch v2 token introspection to validate an access token issued by an authorization server and extract the scopes and patient context at a resource server
hl7.org/fhir/smart-app-launch · 5 steps · unrated
Implement SMART App Launch v2 granular scopes for patient-specific Observation access
hl7.org/fhir/smart-app-launch · 5 steps · unrated

Give your agent this knowledge — and 15,500+ more routes

One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Need this verified for your stack — or a route we don't have yet?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans