Authentication Token for Ingress and Egress APIs1.0.0

Overview

HTTPS with OAuth2 2LO mode is very 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.

 

Audience

This document is intended for developers that are familiar with RESTful APIs, authentication processes (i.e. OAuth 2.0), and API integration. Knowledge of the JSON data format can be helpful when reviewing this material. 

 

Authentication

Most RapidSOS interfaces are authenticated via TWO-LEGGED OAUTH2 (2LO). This entails retrieving a short-lived OAuth 2.0 access token granted using application client credentials. 

Depending on the API interfaces you are interacting with, you will use either the "client credentials" or "password" grant types for obtaining an access token. These are described as follows:

• Client Credentials Grant Type: Used to authenticate your application's access to the API
• Password Grant Type: Used to authenticate your application’s access to the API as well as an individual user’s access to specific resources

The token is valid for authenticating requests to the API for one hour, after which a new token for future requests will need to be fetched. Details for retrieving and using one of these tokens are described below.

Refer to the ALERTS API REFERENCE documentation for additional details.

 

Getting An Authentication Token

This section provides two different methods to retrieve an authentication token. These methods include getting an authentication token using a password grant type, or by using the password grant type.

 

GETTING AN AUTHENTICATION TOKEN USING THE CLIENT CREDENTIALS GRANT TYPE

POST /oauth/token

Request

• Headers
  
   
  • Content-Type: application/x-www-form-urlencoded

 

• Body Parameters

The following body parameters are strings. All of the body parameters are required.

• client_id: Client ID of an application authorized to use the service (as a string).
• client_secret: Client secret of an application authorized to use the service
• grant_type: This parameter should be hardcoded to “client_credentials”

Response

Conditions of the response can include:

• access_token: Short-lived OAuth 2.0 access token
• token_type: Token type descriptor, in this case BearerToken
• issued_at: UNIX timestamp in UTC of the time when the token was issued
• expires_in: Number of seconds after the issued_at time that the access token will expire (defaults to 3600 seconds)

 

GETTING AN AUTHENTICATION TOKEN USING THE PASSWORD GRANT TYPE

POST /oauth/v2/token

Request

• Headers
  
  • Content-Type: application/x-www-form-urlencoded

 

• Body Parameters

The following body parameters are strings. All of the body parameters are required.

•         client_id: Client ID of an application authorized to use the service (as a string).
•         client_secret: Client secret of an application authorized to use the service
•         grant_type: This parameter should be hardcoded to “password”

 

Response

Conditions of the response can include:

• access_token: Short-lived OAuth 2.0 access token
• token_type: Token type descriptor, in this case BearerToken
• issued_at: UNIX timestamp in UTC of the time when the token was issued
• expires_in: Number of seconds after the issued_at time that the access token will expire (defaults to 3600 seconds)

 

Response Codes and Values

 

USING AN AUTHENTICATION TOKEN

To authenticate requests using an access token, requests must include an Authorization header set to the value Bearer <ACCESS-TOKEN> where <ACCESS-TOKEN> is substituted for the retrieved access token.

 

TEST CREDENTIALS

Please contact SUPPORT@RAPIDSOS.COM for test credentials.

 

Sample Code Snippet

RapidSOS grants you a nonexclusive copyright license to use this programming code example (subject to your explicit agreement to RapidSOS Terms of Service) from which you can generate similar functions tailored to your own specific needs. All sample code is provided by RapidSOS for illustrative purposes only. 

These examples may not be thoroughly tested under all conditions. RapidSOS, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs.

IMPORTANT: All API calls require user_name, user_phone, and location at a minimum, as highlighted below, and additional information can supplement these calls.

The following Python code sample demonstrates a client credentials grant type:

import requests

url = "https://api-sandbox.rapidsos.com/oauth/token"

payload = {
  'client_id': '[Your Client ID]',
  'client_secret': '[Your Client Secret]',
  'grant_type': 'client_credentials'
}
headers = {
  'Content-Type': 'application/x-www-form-urlencoded'
}

response = requests.post(url, headers=headers, json = payload)

print(response.json())

 

The following Python code example demonstrates a password credential grant type:

import requests

url = "https://api-sandbox.rapidsos.com/oauth/v2/token"

payload = {
  'client_id': '[Your Client ID]',
  'client_secret': '[Your Client Secret]',
  'username': '[RapidSOS Portal Account Username]',
  'password': '[RapidSOS Portal Account Password]',
  'grant_type': 'password'
}
headers = {
  'Content-Type': 'application/x-www-form-urlencoded'
}

response = requests.post(url, headers=headers, json = payload)

print(response.json())

 

 

Additional References

• Authentication Token for Ingress and Egress APIs Open API Specification