Signing Requests

The Issuu API requires that you sign each request.

When you sign up for API access Issuu assigns an API key and secret to your account. Your API key and secret is only known by you and Issuu. It is important to keep both confidential to protect your account. Only the API key should be included in the request.

Note: Do not share your API key or secret with anyone not even on the Issuu support forum. No one who legitimately represents Issuu will ever ask you for your API key or secret!

To prove that you are the owner of the account making the request, you must include a signature. For all requests, you calculate the signature with your API secret. Issuu uses the API key in the request to look up your API secret and then calculates a signature with the secret. If the calculated signature matches the signature you sent, the request is considered authentic. Otherwise, the request fails authentication and is not processed.

The steps involved in signing a request is as follows:

  1. Sort request parameters alphabetically (e.g. foo=1, bar=2, baz=3 sorts to bar=2, baz=3, foo=1)
  2. Concatenate in order your API secret key and request name-value pairs (e.g. SECRETbar2baz3foo1)
  3. Calculate the signature as the MD5 hash of this string
  4. Include the signature parameter in the request encoded as lowercase HEX
    (e.g. signature=7431d31140cf412ab5caa73586d6324a)

Examples

The examples in this section use the following (non-working) credentials:

API keyqyy6ls1qv15uh9xwwlvk853u2uvpfka7
API secret13e3an36eaxjy8nenuepab05yc7j7w5g

 

Example 1: Listing documents

Suppose we want to list the title and description of our public documents and we want the output format to be JSON. Besides the signature we need to submit the following parameters (See issuu.documents.list for details)

When we concatenate the API secret with the sorted name-value pairs we get:

13e3an36eaxjy8nenuepab05yc7j7w5gaccesspublicactionissuu.documents.listapiKeyqyy6ls1qv15uh9xwwlvk853u2uvpfka7formatjsonresponseParamstitle,description

The MD5 hash of this string is 7431d31140cf412ab5caa73586d6324a. The complete signed request then becomes:

http://api.issuu.com/1_0?action=issuu.documents.list \
    &apiKey=qyy6ls1qv15uh9xwwlvk853u2uvpfka7 \
    &access=public \
    &responseParams=title%2Cdescription \
    &format=json \
    &signature=7431d31140cf412ab5caa73586d6324a

 

Example 2: Uploading a document

If we instead wanted to upload a document with name "racing" and title "Race Cars" (See issuu.document.upload for details) we would need to submit the following parameters:

The string to sign:

13e3an36eaxjy8nenuepab05yc7j7w5gactionissuu.document.uploadapiKeyqyy6ls1qv15uh9xwwlvk853u2uvpfka7nameracingtitleRace Cars
The MD5 hash of this string is 810b910ed5c8a53d704fd062a6001b22. An HTML form for uploading the document could then look something like:
<form action="http://upload.issuu.com/1_0" enctype="multipart/form-data" method="post">
  <input type="hidden" name="action" value="issuu.document.upload"/>
  <input type="hidden" name="apiKey" value="qyy6ls1qv15uh9xwwlvk853u2uvpfka7"/>
  <input type="hidden" name="name" value="racing"/>
  <input type="hidden" name="title" value="Race Cars"/>
  <input type="hidden" name="signature" value="810b910ed5c8a53d704fd062a6001b22"/>
  <input type="file" name="file"/>
  <input type="submit" name="_upload" value="Upload"/>
</form>