Generate key to show a page behind paywall without aid user

Rationale

You can generate a key to show a page behind the paywall even though the user is not authenticated. Using a url with this key, the user is able to look at an article, even when the article is behind a paywall. The key is valid in one month from the timestamp embedded in the signature.

Prerequisites

Contact us by sending an email to amedia-utvikling-apikey@amedia.no telling us why you need this kind of access. This mechanism is typically used by companies monitoring news for clients. We will then create a client ID and a secret for you to use when generating keys.

How to create the key

Creating the key is simple, you can use a script like the following. It is a node.js script, but it easy to port to another language.

This javascript snippets shows how its done. It should be pretty simple to do in all languages that have a library that can sign using hmac with sha1. If not, the implementation of hmac is relatively simple.

// Crypto is the name of the javascript library that
// include signing with hmac
var crypto = require('crypto');

// To create the signature, we sign a string containing 
// contentId, clientId and the date in ISO8601 format
// with timezone Z (UTC). The clientSecret is shared 
// between amedia and clients that should be able to
// create shareable urls. 
// 
// The clientId is the name of
// the client that signs the string. The timestamp 
// gives the period the key will be valid. The key 
// will be valid from the moment defined in the 
// timestamp and the next 31 days. The contentId is 
// the id defining the article to sign.

var contentId = '5-18-164667';
var clientId = 'retriever';
var clientSecret = SECRET;
var timestamp = new Date();

// The string signed is the above values, except the secret,
// concatenated by a forward slashes. Note that the timestamp 
// is converted to ISO8601 format with milliseconds, a valid 
// string is '2015-09-23T12:14:13.766Z'. The 
// format is important, if the implementation uses a date 
// format that is slightly off, the signature will be incorrect.

var textToSign = contentId + '/' +
                 clientId + '/' +
                 timestamp.toISOString();

// The text is then signed using hmac with sha1. The key is the 
// client secret.

var signature = crypto.createHmac('sha1', clientSecret)
                .update(textToSign).digest('hex');

// The key is the timestamp, encoded using ISO8601, the 
// clientID and the signature concatinated by forward 
// slashes. The signature is not secret, and it is impossible
// to get the client secret from the signature.

var params = [timestamp.toISOString(), clientId, signature]
             .join('/');

// The key is added to the url as the key param.

var queryString = "?key=" + params;

For example, a url that gives access to an article can look like this:

http://www.gd.no/sor-midtdalen/vinstra/naringsliv/dataeventyret-er-over/s/5-18-164667?key=2015-09-23T13:33:32.623Z/retriever/9c25014467b3cd8e3c1f094e2cadd04585aa0397

(Note: This URL will work until Oct 23 2015)