Skip to main content

ClientApplication $smart-launch

The $smart-launch operation initiates a SMART on FHIR app launch sequence for a ClientApplication. This creates a SmartAppLaunch context resource and redirects the user to the application's launch URI.

Use Cases​

  • EHR-Embedded App Launching: Launch SMART apps from within an EHR's clinical workflow context
  • Single Sign-On Integration: Provide seamless authentication when launching third-party clinical apps
  • Context-Aware App Initialization: Pass patient or encounter context to SMART apps automatically
  • Patient Portal Integration: Enable patients to launch apps from their portal with proper authorization

Invocation​

GET [base]/ClientApplication/[id]/$smart-launch
POST [base]/ClientApplication/[id]/$smart-launch

Input Parameters​

ParameterCardinalityTypeDescription
patient0..1uuidThe patient ID to include in the launch context
encounter0..1uuidThe encounter ID to include in the launch context

Note: Only one of patient or encounter can be specified, not both.

Output​

The operation returns an HTTP redirect (302) to the ClientApplication's launchUri with the following query parameters:

ParameterDescription
issThe FHIR server base URL (e.g., https://api.medplum.com/fhir/R4/)
launchThe ID of the created SmartAppLaunch resource

Prerequisites​

The ClientApplication must have a launchUri configured. This is the URL where the SMART app expects to receive the launch request. It must be an absolute http:// or https:// URL; other schemes are rejected.

Example​

Request​

GET /fhir/R4/ClientApplication/my-smart-app/$smart-launch?patient=patient123

Response​

HTTP/1.1 302 Found
Location: https://my-smart-app.example.com/launch?iss=https://api.medplum.com/fhir/R4/&launch=launch456

Created SmartAppLaunch Resource​

The operation creates a SmartAppLaunch resource in the background:

{
  "resourceType": "SmartAppLaunch",
  "id": "launch456",
  "patient": {
    "reference": "Patient/patient123"
  }
}

SMART App Launch Flow​

  1. Initiate Launch: Call $smart-launch on the ClientApplication
  2. Redirect: User is redirected to the app's launchUri with iss and launch parameters
  3. Authorization: The app uses the launch parameter during OAuth authorization to retrieve the launch context
  4. Token Exchange: After authorization, the app can exchange the code for tokens and retrieve the launch context

Error Responses​

Status CodeDescription
400 Bad RequestClientApplication ID not specified
400 Bad RequestClientApplication not configured for launch (missing launchUri)
400 Bad RequestlaunchUri is not an absolute http:// or https:// URL
400 Bad RequestBoth patient and encounter specified (only one allowed)
404 Not FoundClientApplication not found

Configuration​

To enable SMART launch for a ClientApplication, set the launchUri field:

{
  "resourceType": "ClientApplication",
  "id": "my-smart-app",
  "name": "My SMART App",
  "launchUri": "https://my-smart-app.example.com/launch"
}