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.
Authorization is requested by including the following parameters in an 'Authorization' http header, or as query string parameters:
- The date of the request in the format: 'YYYYMMDDTHHmmssZ' (example: '20160102T030405Z').
- 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')
- A (sorted, lowercased) list of the HTTP headers used in generating the 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'
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
- - 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
- - 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.