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.
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
).
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:
GET
or POST
)
in capital letters, followed by a single newline (U+000A
).accept
host
(domain name only, no protocol)user-agent
U+000A
) as the separator and append them to the canonical
representation, followed by a single newline character (U+000A
).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
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=
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.
Although HMAC is enabled by default, it can be disabled for troubleshooting. To either enable or disable HMAC authentication, complete the following steps:
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.