Home > Aria Crescendo Documentation > Data Streaming > Data Streaming Authorization

Data Streaming Authorization

Overview

To receive Server-Sent Events (SSE) from Aria, the Data Stream Client must pass an Authentication Token that is obtained via Aria's Data Stream Authentication Service. This Authentication Service is accessible via an HTTPS endpoint.

Note: Once the Data Stream Client successfully connects to Aria and begins parsing SSEs, it is expected to run continually. If the stream is interrupted, you must obtain a new Authentication Token to reconnect the Data Stream Client.

HTTP Requests

  1. To make a request for a token, a POST must be made to the /oauth2/token endpoint:

POST /oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<clientno>&client_secret=<secret>

Alternatively, the service accepts a JSON request of the form:

POST /oauth2/token HTTP/1.1
Content-Type: application/json

{
  "grant_type"    : "client_credentials",
  "client_id"        : <clientno>,
  "client_secret" : <secret>
}

In the above:

  • <clientno> is the Aria client number as a String.
  • <secret> is either the Aria AuthKey or a client-supplied JSON web token (JWT). If <secret> is an AuthKey, it must be one of the currently valid AuthKeys for your Aria tenant.

Authentication will fail if:

  • The Aria tenant AuthKey or client-supplied JWT is rejected.
  • The request is made from an IP address that is not properly whitelisted in your Aria tenant.
  • Client certificates are enabled in your Aria tenant and the wrong certificate or no certificate is presented with the request. See Two-Way SSL Certificates for more information.

For Example:

POST /oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=3286184&client_secret=jsrhnCEg78Mk3stYDxDhTvNmy3fjq7EE

Or, the equivalent in JSON:

POST /oauth2/token HTTP/1.1
Content-Type: application/JSON

{
"grant_type"    :    "client_credentials",
"client_id"        :    "<clientno>",
"client_secret" :    "<secret>"
}

HTTP Response

  1. If the <clientno> and <secret> are verified, the response will be:

HTTP/1.1 200 OK
Cache-Control: no-store, no-cache, must-revalidate
Pragma:    no-cache
Content_Type:    application/json

{
"access_token"    :    "<token>",
"token_type"        :    "<token_type>",
"expires_in"         :    <exp>
}

Where:

  • <token> is the authentication token
  • <token_type> is the authentication type to be used in the HTTP Authorization request
  • <exp> is the lifetime of the token in seconds.

Using the "Token"

  1. The <token> and <token_type> values must be used in HTTP requests to any API that requires tokens. This is done by adding an Authorization header to the Data Streaming - API requests.

Authorization: <token_type> <token>

If a Data Streaming API returns a 401 status code, the current token is invalid and a new one must be retrieved by performing steps 1. and 2. as outlined above. A token is invalid under one of the following conditions:

  • The token has expired.
  • The HTTP request is coming from an IP address not in the range of allowed addresses for your Aria tenant.
  • The certificate that was presented when the token was created was not presented with the API request. (only if client certificates are enabled for the Aria tenant).
  • The token is otherwise bad (i.e the token has been tampered with, or it was not generated by Aria, etc.)

Error Responses

400 Bad Request

Rejected requests will be responded to with a 400 status code. The response will have a content-type of application/json and the response body will be of the form:

{
"error"    :    <error>,
"error_description"    :    <error_description>,
"error_uri"    :    <error_uri>
}

Where:

  • <error> - A String, one of the standard OAuth 2.0 error responses such as: invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type, or invalid_scope.
  • <error_description> - A String, the description of the error. This is an optional field and may not be present in all responses.
  • <error_uri> - A String, a uri referencing more information about the error. This is an optional field and may not be present in all responses.

 

415 Unsupported Media Type

A status code of 415 is returned if the Content_Type of the request is neither application/x-www-form-urlencoded or application/json.

Sample Code

View and download sample Python code for an authorization script.

Source IP and Client Certificates

The Data Streaming Authorization service validates the caller's source IP (and optional client certificate) against your Aria tenant. The token generated by this service will be validated against the same IP ranges and client certificate when it is passed to Aria via your Data Stream Client.

Subtopics 

Data Streaming Overview
Data Stream Client & Server-Sent Events (SSE)
Consuming Aria Data Streams
Subscribing to Objects in the Data Streams
Data Streaming Authentication
Data Streaming Logical Object Model
Data Streaming JSON Representation
Example Data Streaming Code
Data Streaming Frequently Asked Questions

Last modified

Tags

This page has no custom tags.

Classifications

This page has no classifications.
Powered by CXone Expert ®