Skip to main content

Documentation Overview

The RapidSOS App Launcher provides a RapidSOS Partner the ability to make their web application directly accessible and available for launch within RapidSOS Portal. 

This document is intended for prospective or active App Launcher Partners. It provides information on the App Launcher, details required for development and testing, as well as additional useful information to consider. 

 

App Launcher Overview

 

Solution Flow

The App Launcher has the following three core capabilities:

  1. The ability to launch a Partner Web App in a new browser tab via a button click in RapidSOS Portal
  2. The optional ability for a Partner Web App to eliminate additional user logins via the RapidSOS Identity Management API 
  3. The optional ability for a Partner Web App to receive data via the RapidSOS Deeplink API

The following diagram depicts a high-level solution flow of the App Launcher. 

 

Figure 1: App Launcher Solution Overview

 

Solution Details

 

Launching Web Apps

All App Launcher solutions appear within the RapidSOS Tools Menu for authorized users in RapidSOS Portal. Note that App Launcher solutions can be configured to only be accessible when a Portal user has a 911 call selected. Once a user selects an App Launcher solution in the Tools Menu, the corresponding Partner Web App opens in a new browser tab. 

Figure 2: App Launcher Solutions in the Tools Menu in RapidSOS Portal

 

Single Sign-On (Optional)

The RapidSOS App Launcher’s Single-Sign On (SSO) is an optional feature designed to allow RapidSOS Portal users access to a Partner Web App without any additional login to help streamline their operational workflows. Specifically, RapidSOS offers an OpenID Connect (OIDC) compliant identity server for supporting SSO where RapidSOS acts as the Identity Provider (IDP), the Partner Web App acts as the Service Provider (SP), and the SSO is initiated by the SP. The following diagrams show this architecture flow:

Figure 3: SP initiated SSO with OIDC Overview

 

Figure 4: SP initiated SSO with OIDC Flow Diagram

 

Data Exchange (Optional)

The RapidSOS App Launcher’s Data Exchange is an optional feature that allows a Partner Web App to receive data from the RapidSOS Emergency Response Data Platform. Partners utilizing App Launcher’s Data Exchange feature can provide smarter, more contextualized solutions that better streamline ECC workflows than those simply using the RapidSOS App Launcher to redirect users to their web app without any data/context. Partners can receive data from RapidSOS by utilizing the RapidSOS Deeplink API. The following diagrams outline the Data Exchange architecture:

 

Figure 5: Data Exchange Mechanism Overview

 

Partners can be configured to receive the following information from the RapidSOS Emergency Response Data Platform:

  • Phone number of a selected 911 call in RapidSOS Portal
  • Incident location (i.e. lat/long) of selected 911 call
  • LEI Location API token for accessing updated locations of selected 911 call
  • ECC Account ID
  • ECC Jurisdiction Boundary Box

Note: Only applicable partners are eligible to receive call location information. Please contact partnernetwork@rapidsos.com to learn whether your organization is eligible. 

 

Please see the Deeplink OpenAPI Specification here

Note that this link is a truncated version of the Open API Specification

 

Developing and Testing an App Launcher Solution

Partners can develop and test their App Launcher solutions within the RapidSOS Sandbox environment. The following sections are designed to help provide instruction on how you, as a Partner, can develop and test your App Launcher solution. 

For any questions about this guide, please contact please contact RapidSOS at partnernetwork@rapidsos.com

 

Accessing Sandbox

The RapidSOS Sandbox environment provides a complete replica of the RapidSOS Portal browser application including the App Launcher capability. 

You can access RapidSOS Portal on Sandbox by performing the following:

  1. From your web browser navigate to the Sandbox RapidSOS Portal URL: https://sandbox.rapidsosportal.com
  2. Click the Login button at the upper right corner
  3. Enter your Username and Password

 

Please note the following:

  • Login credentials will provide access to a specific RapidSOS Portal account that has its own jurisdictional boundaries. 
  • If you would like to set the jurisdictional boundary of your existing Sandbox Portal account to a different region, please contact partnernetwork@rapidsos.com
  • If you don’t have login credentials, please contact partnernetwork@rapidsos.com

 

Launching a Web App

Your Partner Web App will be available to launch from the Tools Menu in RapidSOS Portal. To launch, a Portal User will select the Tools Menu button in the top left of the screen, locate the your Partner Web App from the Tools drop-down list, and select it. Note that depending on the configuration, your Partner Web App may require the Portal user to have a 911 call selected in RapidSOS Portal in order to launch. 

Upon selection, the browser will open a new tab and the Portal user will be directed to a URL you specify. Please contact partnernetwork@rapidsos.com to let us know what URL your App Launcher solution should open to.

RapidSOS will append a 'rsos_token' query parameter to the specified URL. This secure token will contain an encrypted form of the data you want to receive from RapidSOS. The following sections describe how you can mimic creating this token yourself for testing as well as how you would decrypt this token to retrieve data from RapidSOS. 

 

Creating a Secure Token 

Although in practice RapidSOS will be responsible for generating the secure token and providing it as the 'rsos_token value appended to the URL you specify, the following section contains instructions on how to create a secure token, to help conduct your own testing.

Creating a secure token entails the following steps:

  1. Generating a User JSON Web Token (JWT)
  2. Specifying Data to Receive
  3. Sending a Deeplink request

 

Generating a User JWT

A user JWT authenticates you as a user in the Sandbox environment and is required in order to create a secure token. The following request will generate a user JWT which you’ll need to store for use later on (see the Sending a Deeplink Request section located lower in this document):

curl --location --request POST 'https://sandbox.rapidsosportal.com/v1/scorpius/user/api-token-auth' \

--header 'Content-Type: application/json' \

--data-raw '{

"email": "admin+user@rapidsos.com",

"password": "Test123!"

}'

 

Specifying Data to Receive

The secure token contains the encrypted data that you have specified you would like to receive. RapidSOS enables App Launcher Partners to receive the following information from the RapidSOS Emergency Response Data Platform. 

  • Phone number of a selected 911 call in RapidSOS Portal (“query”)
  • Incident location (i.e. lat/long) of selected 911 call (“incident_location”)
  • LEI Location API token for accessing updated locations of selected 911 call (“access_token”)
  • ECC Account ID (“ecc_account_id”)
  • ECC Jurisdiction Boundary Box (“bounding_box”)

Please contact partnernetwork@rapidsos.com to let us know what data you would like to receive from us.

Below are examples of the data available to receive:

"query": "tel://15555555555"

“incident_location”: {

  "latitude": 40.746523,

  "longitude": -73.980876,

  "location_accuracy": 25.0

},

“access_token”: "abc123",

“ecc_account_id”: "NY_1234",

“bounding_box”: {

  "top_left": {

    "latitude": 40.74,

    "longitude":-73.98

  },

  "bottom_right": {

    "latitude": 40.71,

    "longitude": -73.94

  }

}

Note: Only applicable partners are eligible to receive call location information i.e. "query", incident_location, and access_token. Please contact partnernetwork@rapidsos.com to learn whether your organization is eligible. 

Note: The "query" value should match the "device_number" of any provisioned test call.

 

Sending a Deeplink Request

To generate the secure token, you’ll need to test decrypting (see Decrypting a Secure Token section lower in this document), make a Deeplink API request using both the user JWT you generated (see Generating a User JWT listed above) as well as data want to receive (see Specifying Data to Receive described above).

curl --location --request POST 'https://sandbox.rapidsosportal.com/v1/deeplink/app_launch/1/2' \

--header 'Authorization: Bearer [User JWT]' \

--header 'Content-Type: application/json' \

--data-raw '{

"query": "tel://15555555555"

“incident_location”: {

  "latitude": 40.746523,

  "longitude": -73.980876,

  "location_accuracy": 25.0

},

“access_token”: "abc123",

“ecc_account_id”: "NY_1234",

“bounding_box”: {

  "top_left": {

    "latitude": 40.74,

    "longitude":-73.98

  },

  "bottom_right": {

    "latitude": 40.71,

    "longitude": -73.94

  }

}

}'

 

A successful response will contain a single key/value:

{

  "url": "https://www.partnerwebsite.com?rsos_token=[Encrypted Token]"

}

IMPORTANT: IMPORTANT: The URL 'https://www.partnerwebsite.com' provided in the example must be changed to whatever URL you specify to use. Contact partnernetwork@rapidsos.com to let us know what URL you want your Web App to open to.

Note: The encrypted token is everything after 'rsos_token='

 

Decrypting a Secure Token

Whether you have received a secure token from RapidSOS or you have created a secure token yourself (see Creating a Secure Token described above), you can decrypt the token and extract the data embedded in it by making a POST request to the unauthenticated app token decrypt endpoint using the token as shown in the the following example:

curl --location --request POST 'https://sandbox.rapidsosportal.com/v1/deeplink/partner_web_map/decrypt' \

--header 'Content-Type: application/json' \

--data-raw '{

"token": "<rsos_token value>"

}'

The above returns the unencrypted token payload.

IMPORTANT: The deeplink ‘"partner_web_map" is an example only and must be changed to the specific endpoint that you have configured. 

 

Additional Information

Considerations

For a 3rd-party to make their web application accessible from the RapidSOS Portal via the App Launcher, they must be an approved integration partner. 

Please contact partnernetwork@rapidsos.com for additional information and approval.

 

Requirements

The following technical requirements must be fulfilled.

 

Recommendations

Though not required, it is recommended to consider the following:

  • LEI (Latest Emergency Information) is a Location API that should be used when location data is required with existing credentials. 
  • Use of OpenID Connect which allows for clients of all types, including browser-based JavaScript and native mobile apps, to launch sign-in flows and receive verifiable assertions about the identity of signed-in users.

 

Operations & Usage Compatibility

The following important operational aspects must be clearly understood in relation to implementation and usage compatibility.

URL Whitelisting

As the operability of the web app is the partners responsibility, the partner is also responsible for ensuring the domains and subdomains their web app utilizes are properly whitelisted at agencies. 

Note: RapidSOS can help assist in that process through posting the necessary URLs on the RapidSOS Support and Training Centers when requested. 

ECC Enablement 

The ability to launch your web app in RapidSOS Portal will only be enabled at agencies authorized by you, the partner.

 

Helpful Resource Links

 

For more information about integrating your partner web application solution with RapidSOS Portal, email: partnernetwork@rapidsos.com.

 

About us

We build APIs that share data with first responders to help protect lives.

RapidSOS logo

Contact