Always Learning

Each request you make to the Subscription API, whether you are Creating a Subscription, Retrieving a Subscription, or Deleting a Subscription, must be secured by an Authorization HTTP header:

Request Header

The HTTP header is named Authorization and value is the concatenated values of:

  • Your Principal ID
  • A Timestamp
  • A Signature Token

The values are separated by pipe characters, i.e.,  | . Example:

Authorization: {principal}|{timestamp}|{token}

Request Header Parameters

Name Description
{principal} This is your principal ID.
{timestamp} An ISO-8601 formatted date using GMT time. This parameter must be within 5 minutes of the time on the Eventing server, which your application can verified with a GET request to the unauthenticated /v1/status endpoint.
{token} A signature hash generated from the payload and shared secret using the CMAC algorithm. See the next section.

All parameters are required.

Token Creation

The signature token is generated using some set of parameter values and creating a CMAC algorithm hash from them along with the secret key provided when you got your principal.

The parameters you'll use for the token base string differ for each type of subscription API request. Refer to the API reference for the correct values to use.

Example Token Creation: Payload

For the example, this is the payload for the Create Subscription request. Note the values are bolded for easy identification, and this API requires the values be URL encoded.

Example Token Creation: Base String

The base string is the un-encoded, un-hashed values that will be combined with a secret to create the signature token. For the Create Subscription Request above, the base string looks like this. See the API Reference for more specifics.

The base string is prefixed with timestamp to create the full value to be combined with a secret to create the token.


Example Token Creation: Hashed Values

The full base string (with timestamp) is put through a CMAC algorithm with your secret key. The resulting hash is the signature token. A secret key of 1234567890123456 applied to the example base string produces:


Example Authorization Header (Complete)

Then append the signature token to the HTTP Header value as described above.


Deprecated Approaches

The authorization parameter may be sent differently in existing clients, but these methods will not be supported in the future.

  • An AUTHORIZATION form parameter was previously used in POST requests, but is not necessary now.
  • An Authorization query string parameter was previously accepted as an alternate for GET and DELETE requests, but is not necessary now.
2297 reads
Always Learning