Partner Hash authorisation v1.2

This guide describes a method by which partners (also known as resellers) can authenticate calls to the Permission Marketing API (PMAPI). Partners can use the Partner Hash authentication method to execute PMAPI calls on behalf of their clients. Also, by authenticating as a partner a wider range of capabilities become available through PMAPI. These additional capabilities are referred to as the Permission Marketing Partner API (PMPAPI).

This endpoint applies to partner-auth only. See our guide for more information on partner-auth endpoints and authentication.

Why use Partner Hash authorisation?

Advantages of Partner Hash:

  • Authenticating as a partner provides access to partner-specific API endpoints, and enables enhanced features on some general endpoints.
  • API calls can be executed by a partner on behalf of any company managed by that partner (also a disadvantage).
  • Other advantages match those of the Hash method.

Disadvantages of Partner Hash:

  • The request sender must know the Partner API key, so delegation is not possible unless these details are disclosed to delegates.
  • API calls can be executed by a partner on behalf of any company managed by that partner (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
Partner ID (PID)
int The ID of the authenticating partner.
Company ID (CID)
int The ID of the company on whose behalf the call is to be executed. This argument is optional; some endpoints do not require it.
User ID (UID)
int The ID of the user on whose behalf the call is to be executed. The user must belong to the corresponding company. This argument is optional; if it is not supplied, the administrative user of the corresponding company is implied.
API key (hash)
string A 40-character string consisting of the characters [a-zA-Z]. This key is available on request from Sign-Up.to. Note that this is not the same as a company account’s API key.

Some authentication parameters are optional. This is because some endpoints do not require a company ID at all (and are therefore only available to partners), and others do not require a company ID under certain circumstances. For example, the POST verb on the /account endpoint creates a new company account for the authenticated partner. No company ID or user ID is required for this call.

The user ID parameter is always optional. When authentication data includes a company ID but not a user ID, the system treats the request as if the user ID of the company’s administrator user was supplied. Note that this only applies to the Partner Hash authentication method; other auth methods require a specific user ID.

A shared secret

The Partner 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

POST /v1/account
Date: Sat, 09 Sep 1989 11:00:00 GMT
X-SuT-PID: 4567
X-SuT-CID: 12345
X-SuT-UID: 678
X-SuT-Nonce: 0123456789abcdef0123456789abcdef01234567
Authorization: SuTPartner signature="0123456789abcdef0123456789abcdef01234567"

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

In this request, the X-SuT-PID, X-SuT-CID and X-SuT-UID headers identify a partner, a company account belonging to that partner, and a user belonging to the company account. These credentials are then used to decide whether to authorise the call. 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.

The X-SuT-CID and X-SuT-UID headers are not always required. If you provide the X-SuT-CID header, you may supply a X-SuT-UID header. If you do not supply the X-SuT-CID header you must not include a X-SuT-UID header. Each header must be fully omitted from the request headers and the 40 char hex string if they aren't required, for example:

Example HTTPS request headers

POST /v1/account
Date: Sat, 09 Sep 1989 11:00:00 GMT
X-SuT-PID: 4567
X-SuT-Nonce: 0123456789abcdef0123456789abcdef01234567
Authorization: SuTPartner signature="0123456789abcdef0123456789abcdef01234567"

The X-SuT-CID and X-SuT-UID headers must be fully omitted if they aren't required.

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

POST /v1/account
Date: Sat, 09 Sep 1989 11:00:00 GMT
X-SuT-PID: %partner_id%
X-SuT-CID: %company_id%
X-SuT-UID: %user_id%
X-SuT-Nonce: %random_string%
%partner_api_key%

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 the headers in the canonical string must match the order shown. No other headers may be included in the string. The last line (%partner_api_key%) must contain the partner’s API key, issued by Sign-Up.to. 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: SuTPartner signature="0123456789abcdef0123456789abcdef01234567"