LiveStories IQ developers
Documentation

Authorization

Overview

The Partners API requires authentication with a Key. This key is used to sign every request made to the API.

A key can be generated on the Team Page by Team managers.

Details

Authorization is requested by including the following parameters in an 'Authorization' http header, or as query string parameters:

  • Date
    • The date of the request in the format: 'YYYYMMDDTHHmmssZ' (example: '20160102T030405Z').
  • credential
    • A combination of the following values in strict order, joined by a single '/'
    • API Key ID
    • Request Date in format 'YYYYMMDD'
    • Request scope (currently: 'collection_full', 'collection_create', and 'collection_retrieve')
    • Service Name (internal code name for API: 'burp')
  • headers
    • A (sorted, lowercased) list of the HTTP headers used in generating the signature.
  • signature
    • The generated signature that should be used to validate the request. When used in a query string, this value must always be the final parameter in the query string.
  • expire (optional)
    • The datetime at which the request should no longer be considered valid.
    • Format: 'YYYYMMDDTHHmmssZ'

Process

Signatures are generated using the following rules:

  • 1. Parse+Validate the 'credentials' authorization parameter.
  • 2. Ensure the requested scope is in both the user-assigned scopes, as well as the requested route's scopes.
  • 3. Create a "normalized headers" string by looping over the 'headers' authorization parameter, and for each header appending to the string using the format: `lowercased-header-name:cleaned-header-value\n`. The cleaned header value should consist of the assigned value, with leading and trailing whitespace removed. Any whitespace inside the value should additionally be replaced with a single space.
  • 4. Retrieve the API Secret Key assigned to the specified API Key Identifier
  • 5. Derive a signing key by executing a SHA256 HMAC consecutively on each of the following properties. The hex-encoded output of each function should be used as the input for the next in the series:
    • - a = HMAC(secret, credential.date)
    • - b = HMAC(a, credential.scope)
    • - c = HMAC(b, credential.service)
  • 6. Generate the signing text by SHA256 hashing the following properties in strict order, separated by newline characters:
    • - Request method - GET, POST, PUT, etc
    • - Request path - /collection/f4c96634-0ce3-47cb-975d-0c9ab5df6199
    • - Request query string excluding signature - ?name=foo&value=bar
    • - Normalized headers
    • - The list of header names used to generate the normalized headers
  • 7. Sign the following information using a SHA256 HMAC function on the following values in strict order, separated by newlines characters.
    • - Request date parameter string
    • - Request credential parameter string
    • - Request expiration parameter string, or an empty string if it wasn't included
    • - Signing text SHA256 hex output generated in step 6.
  • 8. Compare the hex output of step 7 with the signature request parameter string. If they match, consider the request authorized. If they do not match, reject the request.