[bt_bb_section layout=”boxed_1200″ lazy_load=”yes” show_boxed_content=”no” allow_content_outside=”no”][bt_bb_row][bt_bb_column lazy_load=”yes” highlight=”no” align_to_edge_column=”no” width=”1/1″][bt_bb_text]
This document provides the information needed to authenticate to the AnalyticsOS℠ Cloud RESTful APIs. Please refer to the AnalyticsOS℠ Cloud API Specification document for the API details.
This specification document corresponds to
- AnalyticsOS℠ Cloud Sensor Ingestion v1.0
- AnalyticsOS℠ Cloud Result Manager v1.0
AnalyticsOS℠ APIs utilize an OAuth Client Credentials Grant (as defined in OAuth 2.0 RFC 6749, section 4.4). The authorization server is provided by a 3rd party service, Auth0. Auth0 refers to this as a Machine-to-Machine (M2M) flow. Figure 1 below is provided by the Auth0 M2M documentation and demonstrates the basics of this flow. In this example, clients utilizing the AnalyticsOS℠ APIs are the “M2M App”.
Figure 1: Auth0 M2M Flow
Obtaining an Access Token
Access Tokens are obtained by making an HTTP POST to the appropriate token URL. An example of this call, along with parameters and response can be found below. Auth0 also provides a more detailed guide on making these requests.
Table 1: Access Token API Parameters
|AUTH_DOMAIN||Token URLs are defined per environment in Table 2 below.|
|grant_type||Set this to “client_credentials”.|
|client_id||Provided by Lone Star to each client using the AnalyticsOS℠ APIs. A unique ID will be provided for each environment (staging/test and prod).|
|client_secret||Provided by Lone Star to each client using the AnalyticsOS℠ APIs. A unique secret will be provided for each environment (staging/test and prod).|
|audience||Audiences are defined per environment in Table 2 below.|
Table 2: Auth Environment Configuration
Upon a successful request, an HTTP 200 response is returned containing the access_token (a signed JSON Web Token), token_type, and expires_in (seconds) values. Example:
Client Secret Changes
Lone Star may periodically rotate Client Secrets. All clients will be notified in advance of those changes, please see the AnalyticsOS℠ Cloud SLA document for more details.
To ensure as little downtime as possible, it is recommended that client applications store multiple secrets as a fallback when transitioning to a new secret. This way clients can update their application configurations in advance of Lone Star enabling the new secret.
Using the Access Token
After obtaining an access token, it can then be passed to the AnalyticsOS℠ API as a Bearer token in the Authorization header of your HTTP request. See the example below.
This provides the API with all the Authentication and Authorization information it needs in order to process the request appropriately.
Access Token Expiration
Typically access tokens are good for 24 hours after being issued. It is recommended the client cache this token when able and only refresh upon or before expiration. Clients should use the expires_in value to determine the token lifetime, as it could vary in the future. If an expired token is presented to an AnalyticsOS℠ API, an HTTP 401 response will be returned with the following payload:
Auth0 Compliance: https://auth0.com/security/
OAuth 2.0 RFC 6749: https://tools.ietf.org/html/rfc6749#section-4.4
Auth0 Machine-to-Machine (M2M) Flow: https://auth0.com/docs/flows/concepts/m2m-flow
Auth0 M2M Guide: https://auth0.com/docs/flows/guides/m2m-flow/call-api-using-m2m-flow