Menu

Lumen help

Constructing an API signature

Signature process

The signature mechanism used by Media portal APIs is HMAC (hash-based message authentication code) and the SHA-1 cryptographic hash function.

The process works as follows:

  • Selected information from your request, including certain HTTP request header fields, is combined into a string.

     

  • A digest of that string is produced using the secret associated with your API key; this is the signature.

     

  • The signature and the API key ID are placed in the HTTP authorization header, and the request is sent.

     

  • Upon receiving the request, Media portal inspects the authorization header and extracts the API key ID.

     

  • Media portal looks up the secret associated with that key. (The secret is known only by the key owner and Lumen.)

     

  • Media portal gathers the other inputs to the digest and builds its own signature. If the two signatures match, the request is authenticated.

Signature format

The authorization HTTP request header field expected from clients is: MPA [API Key ID]:[signature]


MPA (Media portal authentication) is the authentication scheme and signature is a value that is properly constructed as described below.


If an accept header is set in the request, the only valid value is text/XML. Any other value will receive a 406 response.


This signature is constructed in the form of a RFC2104 HMAC‑SHA1 digest. Create a string as follows: [Date ] + “\n” + [RelativePath] + “\n” + [Content‑Type] + "\n" + [HTTP‑Verb] + “\n” + [Content‑MD5]

  • [Date] ‑ value of the Date request header field formatted as, for example, Wed, 29 Apr 2015 +GMT using Java SimpleDateFormat, use: "EEE, dd MMM yyyy HH:mm:ss +GMT" Java SimpleDateFormat using Locale.US), using Locale.US for the current UTC time.
     

  • “\n” ‑ a line feed
     

  • [URI or RelativePath] ‑ path of the request including request scope if applicable (access group, service, network IDs). The RelativePath should include the first forward slash (/) but should not include query string parameters. Examples:

    • /key/v1.0
       

    • /usage/v1.0/1234/BBB1234/my.property.com

  • [Content‑Type] ‑ value of the Content‑Type request header field. For example:
     

    • text/xml
       

    • application/json

  • [HTTP‑Verb] ‑ HTTP method used for the request (e.g. “GET”, “PUT”, “POST”, “DELETE”).
     

  • [Content‑MD5] (optional) ‑ value of the Content‑MD5 request header field, an MD5 digest of the request body. See RFC 2616 Section 14.15. If this request header is set, then it must be included in the signature string.
     

Encode this string as UTF8, construct an HMAC‑SHA1 digest (using the secret), then encode the result in Base64. The output of these steps is the signature.

Unauthenticated requests

Unauthenticated requests are rejected and an HTTP status is sent. Unauthenticated requests include:

  • unsigned requests

  • requests not made over HTTPS

  • requests in which the date header value is older than 15 minutes

If a request fails authorization, Media portal sends a response code to the requester and logs the request (IP address, requested URI, key ID, date and time).

Or, use Postman

If you just want get started faster, try using Postman and skip the need for building a signature. simply use this pre-request script for your collection and attach it at the collection level.

                var moment = require("moment");
/*  Variables need to be added for KEY_ID and SECRET.  Values should be entered as
    Current Values so they will not be exported.  API Keys are created in the Lumen
    Media Portal.
*/
var keyId = pm.variables.get("KEY_ID");
var secret = pm.variables.get("SECRET");

/*
    URL Variables need to be replaced in the signature string
*/
var requestURI = "";
for (i = 0; i < pm.request.url.path.length; i++) {
    var uriPart = pm.request.url.path[i];
    if (uriPart.startsWith("{{") && uriPart.endsWith("}}")) {
        uriPart = uriPart.substring(2, uriPart.length - 2);
        uriPart = pm.variables.get(uriPart);
    }
    requestURI += "/" + uriPart;
}

var requestMethod = pm.request.method;

/*
    PLEASE NOTE THAT CONTENT-TYPE HEADER MUST BE EXPLICITLY SET (DUPLICATED) WHEN SENDING
    A REQUEST WITH BODY (POST,PUT).  OTHERWISE POSTMAN WILL NOT ADD CONTENT-TYPE HEADER
    UNTIL AFTER THIS SCRIPT HAS EXECUTED AND REQUESTS WILL FAIL
*/
var contentType = pm.request.headers.get("Content-Type");
if (!contentType)
    contentType = "";

var md5 = "";
if (pm.request.body) {
    md5 = CryptoJS.MD5(pm.request.body).toString();
}
console.log("md5: " + md5);

var formattedDateString = moment().utc().format('ddd, D MMM yyyy HH:mm:ss') + ' GMT';
var stringToSign  = formattedDateString + '\n' + 
                    requestURI + '\n' +
                    contentType + '\n' +
                    requestMethod + '\n' +
                    md5;
console.log("stringToSign: " + stringToSign);

var stringToSignUtf8 = CryptoJS.enc.Utf8.parse(stringToSign);
var secretUtf8 = CryptoJS.enc.Utf8.parse(secret);
var hmac = CryptoJS.HmacSHA512(stringToSignUtf8,secretUtf8);
var hmacBase64String = CryptoJS.enc.Base64.stringify(hmac);
var authHeaderValue = "MPA " + keyId + ":" + hmacBase64String;

pm.request.headers.add({key: "Authorization", value: authHeaderValue});
pm.request.headers.add({key: "x-l3-date", value: formattedDateString});
pm.request.headers.add({key: "Content-MD5", value: md5});