Launch app within an EHR system

Last updated: Mar 21, 2024

You can use this API action to authorize and authenticate a single sign-on (SSO) request to launch apps within an EHR system.

Redox handles SSO requests 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.

SSO basics

If you want more high-level info, learn about app launch via SSO.

Use cases

This API action may be a good fit for your organization if you perform any of these use cases:

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

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 to launch apps from their system using a Redox launch URL.

Things you need to know

How the SMART app launch works

Shared security responsibilities between your app and Redox

Redirect best practices

Building the launch button

Building the UI

Creating a backup plan

OAuth or OpenID Connect providers

What's next?

Does this API action seem like a good fit for your unique workflow? If so, let your Redox technical account manager know! You can start development by downloading the relevant resource schema (noted in the related action step below) and deciding which data elements you need. Then, use our Redox Nexus Quickstart guide to dive right in.

If you're not engaged with our sales team yet, talk to a Redoxer to get started.

Action steps

1
Launch app within an EHR system
required
2
Make FHIR requests to Redox
required

Launch app within an EHR system

As a reminder, a patient or provider initiates a SMART App Launch by clicking a button in the EHR system's UI. The launch URL is a Redox URL, but when you're configuring your app in the EHR system, you must enter https://launch.redoxengine.com/redirect as the redirect URL when this action happens.

Redox looks up the relevant Redox organization record and redirects the request to the authorization server. The patient or provider is prompted to authorize your application—not Redox—to access the relevant data, then the EHR system is redirected back to Redox.

Redox requests an access token for your app and stores it securely. Then we send the SSO data model with a Meta.SessionId and Meta.SessionBaseURL within the payload.

You can see an example of the SSO payload below, but you can also refer to the resource schema for more details.

Canada URL

If you're operating in Canada, you must tweak the Redox hostname slightly. All you need to do is add a ca in that URL like this: https://api.ca.redoxengine.com.

SSO.Sign-on

Select format

Payload

json

1
{
2
  "NPI": "4356789876",
3
  "Meta": {
4
    "Source": {
5
      "ID": "7ce6f387-c33c-417d-8682-81e83628cbd9",
6
      "Name": "Redox Dev Tools"
7
    },
8
    "DataModel": "SSO",
9
    "EventType": "Sign-on",
10
    "SessionID": "abcdefghijklmnop",
11
    "SessionBaseURL": "https://api.redoxengine.com/fhir/R4/redox-fhir-sandbox/Development"
12
  },
13
  "Name": "Pat Granite MD",
14
  "Visit": {
15
    "Location": {
16
      "Room": "136",
17
      "Type": "Inpatient",
18
      "Facility": "RES General Hospital",
19
      "Department": "3N",
20
      "FacilityIdentifiers": [],
21
      "DepartmentIdentifiers": []
22
    },
23
    "VisitNumber": null
24
  },
25
  "Locale": "en-US",
26
  "Patient": {
27
    "Identifiers": [
28
      {
29
        "ID": "0000000001",
30
        "IDType": "MR"
31
      }
32
    ],
33
    "Demographics": {
34
      "DOB": "2008-01-06",
35
      "Sex": "Male",
36
      "LastName": "Bixby",
37
      "FirstName": "Timothy",
38
      "MiddleName": "Paul",
39
      "PhoneNumber": {
40
        "Home": "+18088675301"
41
      }
42
    }
43
  },
44
  "Subject": "https://healtsystem.com/provider/4356789876",
45
  "IssuedAt": "2023-07-06T14:16:13.834Z",
46
  "LastName": "Granite",
47
  "TimeZone": "America/Chicago",
48
  "FirstName": "Pat",
49
  "Expiration": "2023-07-06T14:31:13.834Z",
50
  "PhoneNumber": {
51
    "Office": "+16085551234"
52
  }
53
}

Make FHIR requests to Redox

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

Query 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 additional FHIR® requests.
Meta.SessionBaseURL	Y	This is a FHIR® base URL that can be used to make additional FHIR® requests. \|

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

Patient/_search

Select sandbox

Select format

Query

bash

1
curl 'https://api.redoxengine.com/fhir/R4/redox-fhir-sandbox/Development/Patient/_search?_redox_session=abcdefghijklmnop' \
2
--request POST \
3
--header 'Authorization: Bearer $API_TOKEN' \
4
--header 'Content-Type: application/json' \
5
--data '{
6
  "given": "Keva",
7
  "family": "Green",
8
  "birthdate": "1995-08-26"
9
}'

Response

json

1
{
2
  "id": "fc7b832c-2a3b-4b17-80e7-2dbc81109f8f",
3
  "type": "searchset",
4
  "entry": [
5
    {
6
      "search": {
7
        "mode": "match",
8
        "score": 1
9
      },
10
      "resource": {
11
        "id": "81c2f5eb-f99f-40c4-b504-59483e6148d7",
12
        "meta": {
13
          "lastUpdated": "2020-10-29T20:06:13.429Z"
14
        },
15
        "name": [
16
          {
17
            "use": "official",
18
            "given": [
19
              "Keva"
20
            ],
21
            "family": "Green"
22
          }
23
        ],
24
        "active": true,
25
        "gender": "female",
26
        "address": [
27
          {
28
            "use": "home",
29
            "city": "Hillsboro",
30
            "line": [
31
              "932 Stehr Vista"
32
            ],
33
            "state": "OR",
34
            "postalCode": "97123"
35
          }
36
        ],
37
        "birthDate": "1995-08-26",
38
        "extension": [
39
          {
40
            "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race",
41
            "extension": [
42
              {
43
                "url": "text",
44
                "valueString": "White"
45
              }
46
            ]
47
          },
48
          {
49
            "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity",
50
            "extension": [
51
              {
52
                "url": "ombCategory",
53
                "valueCoding": {
54
                  "code": "2186-5",
55
                  "system": "urn:oid:2.16.840.1.113883.6.238",
56
                  "display": "Non Hispanic or Latino"
57
                }
58
              },
59
              {
60
                "url": "text",
61
                "valueString": "Not hispanic or latino"
62
              }
63
            ]
64
          }
65
        ],
66
        "identifier": [
67
          {
68
            "value": "kyHGADnvX3xbkU4V9ayaqh",
69
            "system": "urn:redox:redox-fhir-sandbox:MR"
70
          }
71
        ],
72
        "resourceType": "Patient",
73
        "deceasedDateTime": null
74
      }
75
    }
76
  ],
77
  "total": 1,
78
  "resourceType": "Bundle"
79
}

FHIR® is a registered trademark of Health Level Seven International (HL7) and is used with the permission of HL7. Use of this trademark does not constitute an endorsement of products/services by HL7®.