Profiles API and HMAC v1 authorization¶

Based on Personalization Web account configuration, API calls may require authentication in the form of a HMAC-SHA1 message hash as a header within the request. HMAC is a keyed-hash authentication code that calculates a message authentication code (MAC) involving a cryptographic hash function in combination with a secret cryptographic key. SHA1 is one type of cryptographic hash function used in the calculation of an HMAC header; the resulting algorithm is known as HMAC-SHA1.

This authentication scheme protects your data and ensures your secret keys stay secure, and utilizes the Access Key ID and secret access key associated with your Personalization Web subscription.

Setting HMAC authentication as an HTTP request¶

In the Profiles API, HMAC authentication is set as a header in an HTTP request in the following form:

AUTHORIZATION:HMAC [key_ID]:[sig]

where [key_ID] is the access key assigned to your Personalization Web account subscription (for example, asdf23874hfewahJKHJHa), and [sig] is the HMAC-SHA1 hash of canonical representation using the secret access key associated with your Personalization Web account subscription (for example, sdkjfhz[9389PPKJEU).

Generating the canonical representation of the request¶

Before you can calculate the authorization header to authenticate your API call, you first need to generate the canonical representation of the request. To do so, start with the empty string (“”), and then use the following guidelines:

Add the HTTP verb for the request (for example, GET or POST) in capital letters, followed by a single newline (U+000A).
Convert specific header names to lowercase. Currently supported headers are:
- accept
- host (domain name only, no protocol)
- user-agent
Sort the headers lexicographically by header name.
Trim header values by removing any whitespace.
Combine lowercase header names and header values using a single colon as the separator. Do not include whitespace characters around the separator.
Combine the specific headers using a single newline character (U+000A) as the separator and append them to the canonical representation, followed by a single newline character (U+000A).
Append the request URI (the part of this request’s URL from the protocol name up to the query string) to the canonical representation.
Sort all parameters lexicographically (alphabetically) by parameter name, and then join them using a single ampersand as the separator.
Append the parameter string using a single question mark as the separator, unless the query string is empty.

Example¶

You are an Personalization Web and Omnichannel customer whose account ID is EXAMPLEINC, is provisioned in one of the supported geographic regions, and your Profiles API requires authentication. You have an Personalization Web user who wants to retrieve a list of defined segments, and has an Access Key of ABCD and a secret access key of 1234.

The following table describes the process used to handle this example, along with how it can be executed:

Step	Example
Start with an empty string, and then add the capitalized HTTP verb for the request followed by a single newline.	`GET`
Convert the header names to lowercase, sort them by header name, and then trim any whitespace. Combine the header names and values with a colon separator.	host:example-liftapi.lift.acquia.com user-agent:Apache-HttpClient/4.3.5 (java 1.5)
Combine the specific headers using a single newline character and then append them to the canonical representation, followed by a single newline.	GET host:example-liftapi.lift.acquia.com user-agent: Apache-HttpClient/4.3.5 (java 1.5)
Append the request URI (the part of this request’s URL from the protocol name up to the query string) to the canonical representation.	GET host:example-liftapi.lift.acquia.com user-agent:Apache-HttpClient/4.3.5 (java 1.5) /dashboard/rest/EXAMPLEINC/segments
Sort all parameters by parameter name, and then join them using a single ampersand as the separator.	This example does not require parameters, but if it required `parama` with a value of 1 and `paramb` with a value of 2, the sorting and joining result would be: `parama=1¶mb=2`
Unless the query string is empty, append the parameter string, using a single question mark as the separator.	This example does not require parameters, but if it did, the resulting request URI would be: `/dashboard/rest/EXAMPLEINC/segments?parama=1¶mb=2`

The full canonical representation is:

GET host:example-liftapi.lift.acquia.com
user-agent: Apache-HttpClient/4.3.5 (java 1.5) /dashboard/rest/EXAMPLEINC/segments

Creating the authorization header¶

After you have generated the canonical request, you can create the authorization header. Using the canonical request, you can calculate the HMAC header value. If your Personalization Web Access Key ID is ABCD and the secret access key is 1234, the HMAC header value is cvynYFi7SdCWu6KKt+wImfcY17k=.

The full HTTP request is:

GET /dashboard/rest/EXAMPLEINC/segments HTTP/1.1 Host: example-liftapi.lift.acquia.com
Connection: Keep-Alive User-Agent: Apache-HttpClient/4.3.5 (java 1.5)
Authorization: HMAC ABCD:cvynYFi7SdCWu6KKt+wImfcY17k=

Response validation¶

Requests using the GET method will return a response with a Content-MD5 header. This header is the MD5 hash of the response content and can be used for response content validation.

Managing HMAC authentication in Personalization Web¶

Although HMAC is enabled by default, it can be disabled for troubleshooting. To either enable or disable HMAC authentication, complete the following steps:

Click the Admin menu.
In the System menu, click Manage customers.
In Account ID, click your ID.
In the API Authentication settings, depending on the API call that you are using, select or clear the appropriate checkboxes to either enable or disable your HMAC authentication settings:
- Enable Segment REST Api HMAC Authentication - Controls HMAC authentication for segment calls in the Profiles API
- Enable Event Import REST Api HMAC Authentication - Controls HMAC authentication for event imports in the Profiles API
- Enable File Export REST Api HMAC Authentication - Controls HMAC authentication for file exports in the Profiles API
- Enable Visitor Query REST Api HMAC Authentication - Controls HMAC authentication for visitor queries in the Profiles API

Code examples¶

We have developed several code examines that you can use to help you understand how to make calls to the Profiles API reference using different programming languages:

PHP code example: Makes a call to the Personalization Web REST API based on the parameters you’ve provided it. getMakeAPICall is the entry point of the example.
Java code example: Makes a call to several Personalization REST APIs. The entry point of the example is the main method.

Looking for something?