All requests are authenticated using two special signature headers added by the client and checked by the NetStorage system.

One of these headers contains basic authentication information about the specific request, and the other contains similar information encrypted with a shared secret (your upload account Key). This allows the origin server to perform several levels of authentication to ensure that the request is coming to NetStorage from an authorized client, without tampering.

The "X-Akamai-ACS-Auth-Data" authentication header

X-Akamai-ACS-Auth-Data: [version], [], [], [time], [unique-id], [uploadAccountId]

This is the first required header, and is referred to as "[signature header 1]" throughout this documentation. The information required for each of its variable values is described here:

Field                  Description
[version] This indicates the authentication encryption format.
Version 3. HMAC-MD5([key], [data] + [sign-string])
Version 4. HMAC-SHA1([key], [data] + [sign-string])
Version 5. HMAC-SHA256([key], [data] + [sign-string])
[]This is a reserved field. Specify as "".
[time]1The current epoch time. For example, "1497896370" is "Monday, June 19, 2017 11:19:30".

Any time between the timestamp in the initial request, and the time this header is actually received, plus 60 seconds is accepted.
[unique-id]This is a unique ID chosen by the client with some randomness that will guarantee uniqueness for multiple headers generated at the same time for multiple requests.
[uploadAccountId]The name ("Id") of an upload account provisioned to access the target storage group serves as the uploadAccountId. This value must not contain special characters such as commas and spaces. Read about upload accounts in the Get started topic.

1 The [time] on a client using the API must be within one (1) minute of the actual time. If the time varies more than this, then authentication will fail with an “HTTP 403” error. It is suggested that any client using the API run “ntp” (Network Time Protocol) to properly establish time

The "X-Akamai-ACS-Auth-Sign" header

This is second required header, and is referred to as "[signature header 2]" throughout this documentation. It contains a single variable value.

X-Akamai-ACS-Auth-Sign: [base-64-encoded-signature]

The “base-64-encoded-signature” variable

This variable is comprised of a generated signature based on a specific algorithm.

It utilizes the [version] value specified in the X-Akamai-ACS-Auth-Data header. This API supports versions 3, 4, and 5. These are the basic structures of the base-64-encoded-signature algorithm depending on the version in use:

3HMAC-MD5([key], [data] + [sign-string])This version is deprecated and shouldn't be used
4HMAC-SHA1([key], [data] + [sign-string])This isn't the preferred cipher.
5HMAC-SHA256([key], [data] + [sign-string])This is the preferred cipher.

In this algorithm, the following variable values are applied:

  • [key]: The internally-generated Key. This is the value gathered when provisioning access to the API.
  • [data]: The full contents of the X-Akamai-ACS-Auth-Data header.
  • [sign-string]: The string to sign is equal to the example below.
URL + “\n” + “x-akamai-acs-action:” + X-Akamai-ACS-Action value + “\n”

The “sign-string”

In the context of the API, the [sign-string] is formed by using the following:

  • The Request Path: This is the first line of the request, without the surrounding method (PUT or GET), the protocol, or space character delimiters.
  • A single line feed character - This is represented here with a newline -- “ \n ” -- character)
  • The string “x-akamai-acs-action:” followed by the value of the X-Akamai-ACS-Action header - Ensure that any preceding and trailing whitespaces are removed.
  • A final line feed character: Again, this is represented by \n.

For example, the following request is to be sent:

    PUT /[CP Code]/[path]/[file.ext] HTTP/1.1
    Host: [Domain Prefix]
    X-Akamai-ACS-Action: version=1&action=upload&md5=0123456789abcdef01234 56789abcdef&mtime=1260000000

The resulting sign-string would be as follows. (And, “ \n” represents the line feed character (ASCII code 10.)

/[CP Code]/[path]/[file.ext]\nx-akamai-acs-action:version=1&action=upload&md5=0123456789abcdef0123456789abcdef&mtime=1260000000\n


The md5 shown in the example above is not a true representation of a hash of the values provided. It is simply a placeholder included for example purposes, only.