Access to the GoPAD API is restricted to authorised users only, and uses a custom HTTP scheme based on a keyed-HMAC (Hash Message Authentication Code) for authentication. Developers are issued with an access key and a private key when they register to use the GoPAD API and must use these to generate a signature, which must be included with each request.

When GoPAD receives an authenticated request, it fetches the private key that you claim to have and uses it in the same way to compute a signature for the message it received. It then compares the signature it calculated against the signature presented by the requester. If the two signatures match, the system concludes that the requester must have access to the private key and therefore acts with the authority of the principal to whom the key was issued. If the two signatures do not match, the request is dropped and the system responds with an error message.

It is therefore essential that you do not expose your private key.

The GoPAD API uses the standard HTTP Authorization header to pass authentiation information, which has the following form:

Authorization: GPAPI timestamp:AccessKey:Signature

The timestamp part of of the Authorization header is the timestamp which you used to produce your Signature. The timestamp must be within 300s of the GoPAD system time.

The AccessKey part of the Authorization header represents the access key that was used to compute the signature and, therefore, the developer making the request.

The Signature part of the Authorization header will vary with each request. If the request signature calculated by the system matches the signature included with the request, the requester will have demonstrated posession of the private key. The request will then be processed under the identity, and with the authority, of the developer to whom the key was issued.

A Signature can only be used once. Therefore, two identical requests with the same timestamp cannot be made.

Process to Produce a Signature

  1. Generate a HMAC-SHA256 using your timestamp as the data and your private key as the key.

    E.g. $hash1 = hash_hmac('sha256', {timestamp}, {private key}, true);

  2. Generate a HMAC-SHA256 using your access key as the data and the HMAC from step 1 as the key.

    E.g. $hash2 = hash_hmac('sha256', {access key}, $hash1, true);

  3. Generate a signing string by concatenating the following with "_":
    1. The HTTP verb of the request (upper case).
    2. The URI of the API resource you are using, including the initial forward and any query string.
    3. The content length. For requests with no body, such as GET requests, 0 (zero) should be used.

    E.g. $signingString = 'GET_/api/v1/tasks/173730_0';

  4. Generate a base64 encoded HMAC-SHA256 using your signing string as the data the HMAC from step 2 as the key.

    E.g. $signature = base64_encode(hash_hmac('sha256', $signingString, $hash2, true));

The signature produced in step 4 can then be used in the Authorization header.