Hash authorisation v1.2

This guide describes a method of authenticating calls to the Permission Marketing API (PMAPI) using credentials supplied by the Sign-Up.to platform. A 32-character hex string is required in conjunction with a company ID and user ID. An SHA-1 digest is created from these credentials and provided as the signature.

Hash-authenticated requests can be issued using the PMAPI client library. We have also coded an example showing how this method can be used.

Why use Hash authorisation?

Advantages of Hash:

  • No credentials are generated that could subsequently be lost or compromised (i.e. a Token).
  • There is no need to create storage for a Token.
  • Once the CID and API key are known, a request may be made on behalf of any valid user of the company by setting the UID accordingly (also a disadvantage).
  • No need to code for the "token expiry" case.

Disadvantages of Hash:

  • The request sender must know the CID and API key of the company, so delegation is not possible (without disclosing these details to delegates).
  • Once the CID and API key are known, a request may be made on behalf of any valid user of the company by setting the UID accordingly (also an advantage).

When authenticating with the Hash method, all actions will be carried out on behalf of the nominated user. Please note, some functionality and content is restricted on a per user basis.

What do I need for authorisation?

The credentials involved in this authentication method are:

Parameter Type Description
Company ID (CID)
int The ID of the authenticating Sign-Up.to account.
User ID (UID)
int The ID of the authenticating user, available in a Sign-Up.to account.
API key (hash)
string A 32-character hex string, composed of the characters 0-9 and a-f, generated by (and available in) a Sign-Up.to account.

A shared secret

The Hash authentication method uses a shared secret. The API key value (the secret) is not transmitted to the server as part of the request: instead it is used as a salting value when generating a signature. A hash-authenticated PMAPI HTTPS request has this format:

Example HTTPS request headers

GET /v1/folder HTTP/1.1
Host: api.sign-up.to
Date: Tue, 30 May 2013 12:34:56 GMT
Accept: application/json
X-SuT-CID: 12345678
X-SuT-UID: 234567
X-SuT-Nonce: 0123456789abcdef0123456789abcdef01234567
Authorization: SuTHash signature="58fbc47de328879 ...etc

Please note that all PMAPI requests must be made over SSL (HTTPS).

In this request, the X-SuT-CID and X-SuT-UID headers identify a user and company on whose behalf the call is made. The X-SuT-Nonce header contains a randomly generated string of up to 40 characters. This string, which is used in the signature generation process, uniquely identifies the request in order to prevent replay attacks. The Authorization header contains the request signature, a 40-character hex string generated using parameters from the request.

Constructing your signature

The signature is the SHA-1 digest of a canonical string containing certain request parameters. The format of the canonical string is:

Format of the canonical string

GET /v1/folder
Date: Sat, 09 Sep 1989 11:00:00 GMT
X-SuT-CID: %company_id%
X-SuT-UID: %user_id%
X-SuT-Nonce: %random_string%

Please note that all PMAPI requests must be made over SSL (HTTPS).

In accordance with the HTTP specification, lines must be terminated by \r\n (DOS-style) line breaks. The first line contains the request verb and API path; any query string (e.g. ?id=123) must not be included. Header names (e.g. X-SuT-CID) must be separated from their values by a colon and a single space character (ASCII code 32), i.e. :. The order of headers in the canonical string must match the order shown. No other headers may be included in the string. The last line (%api_key%) must contain the company's API key, issued by the Sign-Up.to platform. Note that the line containing the API key does not have a terminating line break.

The request signature is generated by calculating the SHA-1 digest of the canonical string. The signature is then supplied with the request, in the Authorization header:

Example authorization header

Authorization: SuTHash signature="0123456789abcdef0123456789abcdef01234567"