Request Signing

Overview

This page explains how to generate a HMAC-SHA1 signature for a HTTP request. Request signature is the API request parameter api_sig which is added to every request to verify request user’s authenticity on behalf of which the request is made.

The request used to demonstrate request signing is a POST to https://infogr.am/service/v1/infographics. The raw request looks like this:

POST /service/v1/infographics HTTP/1.1
Host: infogr.am
Content-Type: application/x-www-form-urlencoded
Content-Length: 176

api_key=nMECGhmHe9&content=%5B%7B%22type%22%3A%22h1%22%2C%22text%22%3A%22Hello%20infogr.am%22%7D%5D&publish=false&theme_id=45&title=Hello&api_sig=bqwCqAk1TWDYNy3eqV0BiNuIERQ%3D

Much of this description has been inspired by request signing description on Twitter, thus it might be a valuable resource as well.

Signature generation algorithm (in pseudocode)

1. Initialize empty string signatureBase
2. Append request method string to signatureBase
3. Append “&” character to signatureBase
4. Append percent-encoded request path (NOT the query string) to signatureBase
5. Append “&” character to signatureBase
6. Initialize empty string parameterString
7. For every key/value pair in query string or POST/PUT data
   1. Append percent-encoded key to the parameterString
   2. Append “=” character to parameterString
   3. Append percent-encoded value to the parameterString
   4. If there are more key/value pairs, append “&” character to the parameterString
8. Append percent-encoded parameterString to signatureBase
9. Sign the signatureBase string using HMAC/SHA1 algorithm and your secret key as a key which yields signatureBytes
10. Convert signatureBytes to string using base64 encoding. The result is the request signature

Collecting the request method and URL

To produce a signature, start by determining the HTTP method and the base URL of the request. Infogr.am REST API uses four request methods:

• GET
• POST
• PUT
• DELETE

HTTP method:

POST

The base URL is the URL to which the request is directed, minus any query string or hash parameters. Always use “https://” protocol with the Infogr.am API.

Base URL:

https://infogr.am/service/v1/infographics

Collecting parameters

Next, gather all of the parameters included in the request. There are two locations for these parameters: the query string of the URL (for GET and DELETE requests) and the request body (POST, PUT).

In HTTP requests parameters are URL-encoded but you should collect the raw values. In the raw HTTP request above, the parameters are as follows:

These values need to be encoded in a single string which will be used later on. The process of building the string is the following:

1. Sort the list of parameters lexicographically by their keys
2. For each key/value pair:
   1. Percent-encode key and append it to the output string
   2. Append the ‘=’ character to the output string
   3. Percent-encode value and append it to the output string
   4. If there are more key/value pairs remaining, append a ‘&’ character to the output string

Parameter string:

api_key=nMECGhmHe9&content=%5B%7B%22type%22%3A%22h1%22%2C%22text%22%3A%22Hello%20infogr.am%22%7D%5D&publish=false&theme_id=45&title=Hello

Percent-encoding

When producing the signature base string, it is important to correctly encode parameter strings. Infogr.am API services expect those parameters percent-encoded accordingly to RFC3986, Section 2.1.

Producing the signature base string

The signature base string is a result of concatenation three strings we’ve produced before in the following order: the HTTP request method, percent-encoded base URL, and the percent-encoded parameter string, joined with a ‘&’ character between the neighboring components.

Signature base string:

POST&https%3A%2F%2Finfogr.am%2Fservice%2Fv1%2Finfographics&api_key%3DnMECGhmHe9%26content%3D%255B%257B%2522type%2522%253A%2522h1%2522%252C%2522text%2522%253A%2522Hello%2520infogr.am%2522%257D%255D%26publish%3Dfalse%26theme_id%3D45%26title%3DHello

Please mind that every component before the concatenation should be percent-encoded, hence in the resulting signature base string you should have exactly two ‘&’ characters.

Getting a signing key

The signing key is your API account’s percent-encoded secret key which should be kept secret. Note that you should never explicitly transfer it and noone should ask you to type it anywhere. This key should be “known” by your application only.

Signing key:

da5xoLrCCx

Calculating the signature

Finally, the signature is calculated by passing the signature base string and signing key to the HMAC-SHA1 hashing algorithm. The details of the algorithm are explained here, however there are implementations of HMAC-SHA1 available for every popular programming language.

The output of the HMAC signing function is a binary string. This needs to be base64-encoded to produce the signature string. For example, the output given the signature base string and signing key given on this page is:

6e ac 02 a8 09 35 4d 60 d8 37 2d de a9 5d 01 88 db 88 11 14

That value, when converted to base64 is the signature for this request:

Request signature:

bqwCqAk1TWDYNy3eqV0BiNuIERQ=