API Environments and Credential Management

Overview

Each RapidSOS service 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.

Environments

The following environments are defined in each API specification:

  • Production
  • Sandbox

When a Tech Partner API is used on one environment, the data is unique to that environment and not accessible by output APIs of other environments.

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

Sandbox

  • 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

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.
  • 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

  • Each set of credentials rate-limited to 1000 requests per minute, and monitored for abuse against a set of heuristics

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-partner basis in a B2B2B type use case