API Environments and Credential Management

Overview

Each output interface to RapidSOS systems (commonly referred to as the Intelligent Safety Platform) is deployed on several different infrastructure environments to facilitate development and testing new releases, preserving the security and privacy of live customer data.

Any details specific to an interface will be described in the documentation for that interface, however, all of them share the common base described in this document.

Audience

This document references input and output APIs.

  • Though this document focuses primarily on output APIs, similar considerations for input APIs and SDKs are described in each of their respective documentation pages.
    • However, the descriptions of the root hosts of each environment below still apply - when an input API is used on one environment, the data is unique to that environment and not accessible by output APIs of other environments.

Environments

The following environments are defined in each API specification:

  • Production
  • Sandbox

Production

  • Full deployment of microservices to geographically-redundant clusters, API rate-limiting/throttling features enabled for denial of service protection, etc.
  • Full data access controls
  • All deployments handling live 9-1-1 in PSAPs should use this environment
  • LIS interface only returns location records created within the last 10 minutes
  • LEI latest location query interface only returns location records created within the last 60 minutes.
    • Queries using the start and limit parameters can still be used to query outside this range
  • LIS and LEI interfaces only return location records with an uncertainty_radius less than or equal 500 meters

Sandbox (production mirror with dummy data)

  • Exact clone of the production environment, with versions of software deployments identical to production
  • Primarily intended for developer integration and testing
  • Data access controls are lax compared to production - sensitive data should not be sent here
  • No guarantees of uptime or data retention
  • LIS interface returns location records created within the last 10 years
  • LEI latest location query interface returns location records created within the last 10 years
    • Queries using the start and limit parameters can still be used to query outside this range
    • LIS and LEI interfaces return location records with an uncertainty_radius less than or equal 10,000 meters

Authentication & Encryption

RapidSOS currently supports two main modes for each interface:

  1. HTTPS with HTTP basic authentication
  2. HTTPS with OAuth2 2LO

Details for both modes are provided:

  • HTTPS with HTTP basic authentication
    • a mechanism that allows encrypted access to be conducted over the internet with usernames and passwords issued by RapidSOS to the interconnecting vendor or agency.
    • Standard TLSv1.2 according to RFC 5246 must be used with single-sided authentication (server provides an X.509 certificate, but the client may be unauthenticated in the TLS handshake)
    • Please note that TLSv1.0/TLSv1.1 are deprecated and should not be used
    • Credentials must be sent in HTTP request headers following HTTP Basic Authentication according to RFC 2617.
    • Requests with missing or unrecognized credentials will result in a standard HTTP 401: Unauthorized error.
    • For certificate authority, by default RapidSOS uses DigiCert (root certificate) - alternatives may be configured upon request.
  • HTTPS with OAuth2 2LO mode
    • similar to HTTPS with Basic Authentication, except that it includes an extra API call to an authentication server to obtain short-lived authorization Bearer tokens to be used in each request.
    • In general this method is considered more secure than basic authentication since it is safe to log the entirety of the HTTP traffic (including headers) without compromising the credentials (since the tokens expire within 1 hour).
      • When possible, RapidSOS recommends the use of this mode instead of Basic Authentication.

The sandbox described in this documentation accepts both modes simultaneously.

Credential Management

For All Environments

  • Authenticated HTTPS interfaces enabled, keys available upon submitting a request to RapidSOS and choosing Credentialing Support
  • Keys expire after 365 days
  • Each set of credentials rate-limited to 1000 requests per minute, and monitored for abuse against a set of heuristics
  • Location interfaces require the provisioning of a geofence that matches jurisdictional authority for the key. Your RapidSOS contact will be able to make sure any required geofences are provisioned on production keys.

Production Credential Authorization

Note for production credentials: production keys are to be granted in conjunction with a deployment to an entity with authorization to receive the information from live 911 calls (i.e., a municipality or other 911 operating authority), or their vendors that have been authorized to administer systems on their behalf. Thus, any production credential requests initiated through the web portal will sit in a pending state until RapidSOS can verify the legitimacy of the request.

Flow for Authorization

An example of a site onboarding flow might be similar to the following:

  1. New site deployment is identified
  2. Authorized PSAP personnel submits a credential request through RapidSOS Portal.
  3. Credentials are issued to PSAP personnel and managed through RapidSOS Portal.
  4. As part of the activation, RapidSOS must provision geofence information for the API key

Geofencing

Internal to the RapidSOS system, each production API needs to be provisioned with a geofence indicating a broad area of applicability. These geofences are used to prevent abuse by locking the locations any key can query for to those inside the geofence.

For example, a key issued with a geofence that surrounds only the greater Boston metro area cannot be used to return a location that is in Florida: if such a key queries a number that has such a location, the interface will return a 404 response as if no location is found.

These bounding geofences are created in conversation with authorities during the key provisioning process - the RapidSOS public safety will always endeavor to conform to the requirements of the jurisdiction in question, e.g. to make the bounding boxes as large as necessary to service their call volume (handling regions where transfer calls are common, for example).

Credential Usage Guidelines and Limits

  • These expiration and rate limiting are configurable if need be, but it is not recommended to deviate too far from security best practices whenever possible.
  • It is expected that credentials would normally be deployed on a per-site basis
    • for example, each PSAP would use a different set of credentials (or multiple different sets). This is so that if ever there is a need to revoke access - for example if there is ever a security breach, a client/server glitch creating spam, etc - revocation only affects a small number of sites / workstations.
    • RapidSOS will coordinate email and phone renewal reminders to holders of active production credentials three months in advance of expiration, with regular follow-up and support until renewal is accomplished.