Launch app within an EHR system

You can use this API action to authorize and authenticate an SSO request in order to launch apps within an EHR system. Typically, you can use this for: 

  • Allowing a provider or patient to access your app directly from their system; 
  • Enabling SSO for you to make FHIR® API requests to your connection’s system; or
  • Allowing Redox to automatically refresh access tokens for your system.

Redox handles the SSO request with OAuth 2.0. We store the access tokens for you and automatically refresh the tokens as needed. 

This API action allows you to quickly and efficiently integrate with a new connection’s system by using an existing configuration with minimal code changes.

Supported systems 

You can use this API action with the Redox FHIR® API. For SSO, you can use SAML, SMART, or other SSO schemes. Redox is compatible with any OAuth or OpenID Connect provider. When using SMART, you must register your app with a provider that supports SMART. 

Your connection must have their own FHIR® API in order to launch apps from their system using a Redox launch URL.

Special considerations

Building the launch button

Your connection requires a launch button in their own system to trigger the SSO request to Redox. This button must be developed by your connection.  

Building the UI

Redox facilitates the SSO request, but we don’t build a UI for launching and accessing your app. Part of using this API action requires that you develop and maintain the UI for your connection.

Backup plan

Not every connection may be able to support launching an app from within their system. We recommend that you have a backup plan for entering your app so that any of your connections can use your app, regardless of their SSO capabilities. For example, you could make your app available with a URL that allows patients or providers to log in separately if SSO is not available.

OAuth or OpenID Connect providers

After registering your app, you can check out these sandbox environments that work with Redox: 

Each vendor requires different information, but one required element you must include is this redirect uri: https://launch.redoxengine.com/redirect. Essentially this tells the authorization service that it's okay for Redox to handle the authorization and SSO request.

Flow for SMART app launch

Follow the outline below to get a better understanding of how SMART App Launch works with Redox:

  1. Either the patient or a provider at a healthcare organization initiates a SMART App Launch by clicking a button in the EHR system’s UI.
  2. The launch URL is a Redox URL. Redox uses this URL to look up your Redox organization record, then redirects the request to your authorization server.
  3. The patient or provider is prompted to authorize your application—not Redox—to access the relevant data.
  4. The EHR system is redirected back to Redox.
  5. Redox requests an access token on behalf of your app and stores it securely.
  6. Redox sends an SSO message with a SessionID to your endpoint. You can use this SessionID to initiate FHIR® requests in context of the patient or provider’s specific session. 
  7. Your endpoint records the SessionID and redirects to either a static page or completes SSO.
  8. Redox redirects the patient or provider to your configured SSO URL.

When making subsequent FHIR® API requests, your app should include the SessionID (from step #7) to use the SSO access token (from step #5) when sending a request to your connection’s system.

Action steps

  • 1
    Launch app within an EHR system
    required

Query parameters

After enabling SSO, you must include these query parameters in the URL when making subsequent API requests:

Parameter
Required
Notes
Meta.SessionID
Y
Redox provides a unique SessionID that you must include in the _redox_session query parameter of the URL to make subsequent FHIR® requests.
Meta.SessionBaseURL
Y
This is a FHIR® base URL that can be used to make subsequent FHIR® requests. |

Refer to the resource schema for more details.

Returned results

Typically, you receive the provider userID and name in the response. Most often, you also receive the patient ID, but not always. We recommend pairing your request with a patient search or other enrollment method to guarantee receiving the patient ID or other patient details.

Query/Response
Open dropdown
Open dropdown