Hub API Reference

[This topic is pre-release documentation and is subject to change.]

After you create a Customer Insights Hub using the Azure Portal or through a Create Hub (ARM) operation, a new set of Hub APIs is available for use. (The base endpoint for the hub is available in the response from the Get Hub (ARM) operation.) These APIs fall into the following two general groups:

  • Hub Management APIs support type modeling, security, application, widget,and connector management. There is a high degree of commonality between this API set and the Hub Management APIs via ARM. The APIs in this first group are accessed through endpoints of the form:   https://<hubName>.api.azurecustomerinsights.com/manage/<resourceName>
  • Hub Data APIs support working with actual instance data of the various customized entity types (also referred to as entity sets). These APIs conform to the OData specification, and are accessed through endpoints of the form:   https://<hubName>.api.azurecustomerinsights.com/manage/<resourceName>

Authorization to Hub APIs

Hub APIs support access through Shared Access Signature (SAS) tokens as well as Azure Active Directory (AAD).

As token-based authorization (authz) is enabled by SAS policies that we store in the system. Each SAS policy has two symmetric keys used to sign the SAS tokens. Each policy also holds the information about the access rights it grants to a HTTP call (Read, Write, Manage). When a hub is provisioned, it gets assigned a default SAS policy named as RootManageSharedAccessKey. This is an 'all access' SAS policy for the hub. The SAS token is specified in the Authorization header of the HTTP request sent to the Hub API endpoint. The format of the token is as follows:

     SharedAccessSignature-sig=<signature>&se=<expiry>&skn=<policyName>&sr=<resourceUri>

Where the parameters have the following meaning:

Token Parameter Required Description
expiry Yes The URL-encoded epoch time till which the token is supposed to be valid.
policyName Yes The URL-encoded name of the SAS policy (associated with the hub being called) using one of whose keys the token has been signed.
resourceUri Yes the URL encoded URI that is signed. The actual http request URI should be under this URI for authz to succeed.
signature Yes The HMAC SHA256 hash of the string "<resourceUri>\n<expiry>" computed using either of the two keys of the SAS policy specified by <policyName>

For AAD-based authz, the calling user/application needs to get a token for resource “https://azurecustomerinsights.com” from their AAD tenant endpoint. The token is validated for the following in the Customer Insights service:

  • Signature validation
  • Audience validation
  • Issuer validation: The token should be from the parent tenant for the Azure subscription in which the Customer Insights Hub was created.

The Customer Insights RBAC APIs configure access (authorization) to principals. Depending upon the API being invoked, the calls are authorized accordingly.