Client Authentication

Two methods are available for client authentication: Simple Authentication and authentication using an Authorization Signature.

Simple Authentication

For simple authentication, just pass in your API client's assigned UserName and Password request headers with your assigned UserName and Password.
The following is a sample request using simple authentication:

HTTP Request

POST /rest/system/status/secure-echo HTTP/1.1
Content-Type: application/json; charset=utf-8
UserName: UserName
Password: Password
Host: sandbox.api.gnsvc.com
Content-Length: 37
Accept-Encoding: gzip, deflate
AdvancedErrorCodes: True

Body

Authorization Signature

To use the more secure Authorization signature, you must generate an Authorization signature using your assinged UserName, Password and ClientApplicationSecret, plus a Unix Timestamp representing the current date and time in UTC. For security purposes, the timestamp is valid for only one minute and will be rejected if it is older than one minute.

The generated Authorization signature is passed in as the "Authorization" http header, along with the "Timestamp" header, which is used to pass in the timestamp used to generate the Authorization string.

The Authorization signature is created by HMAC-256 signing the following string concatenation, using your assigned ClientApplicationSecret as the key, and Base64 encoding the results:

Username + SHA1-Hashed Password as Base64-encoded string + UTC Timestamp

For example, to create an Authorization signature with following UserName, Password and ClientApplicationSecret and Timestamp:

UserName: UserName
Password: Password
ClientApplicationSecret: 617e0ed8-7531-44a4-bd64-2b246291c600
Timetamp: 1397500408
You would first SHA1-Hash the password and represent it as a Base64-encoded string:

i+PJQ7Fgn/+/xRqtZm0KBK34PJ0=

Then you would form the concatenated string as indicated above, with the following result:

UserNamei+PJQ7Fgn/+/xRqtZm0KBK34PJ0=1397500408

HMAC-256 signing the above string using your ClientApplicationSecret as the key, the Base64 encoding the results would give you the following Authorization signature:

/pO71xQDqtAyMi9KOAzg4zUlNOhoFvROo4ZZp0GDqLE=

Be sure to use the letter casing as it was issued for your UserName and Password. Your ClientApplicationSecret must be lower-cased prior to hashing.

Below are some code samples that demonstrate how to build an Authorization signature in some common languages. v id="code-samples"> 
using System;
using System.Security.Cryptography;
using System.Text;

namespace MyGolfApp.Security
{
    public class AuthorizationSigner
    {
        public static string GetSignature(string username, string password, int timestamp, string secret)
        {
            string toHash = String.Format("{0}{1}{2}", username, Convert.ToBase64String(HashSha1(password)), timestamp);
            return Convert.ToBase64String(HashHmac256(Encoding.UTF8.GetBytes(toHash), Encoding.UTF8.GetBytes(secret)));
        }

        private static byte[] HashHmac256(byte[] data, byte[] key)
        {
            using (var hmacAlgorithm = new HMACSHA256(key))
            {
                hmacAlgorithm.ComputeHash(data);
                return hmacAlgorithm.Hash;
            }
        }

        private static byte[] HashSha1(string s)
        {
            SHA1 sha1 = SHA1.Create();
            byte[] octets = Encoding.UTF8.GetBytes(s);
            byte[] hash = sha1.ComputeHash(octets);

            return hash;
        }
    }
}

import java.security.MessageDigest;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class AuthorizationSigner {
	
    public static void main(String []args){
        System.out.println(getSignature("UserName", "Password", "1397500408", "617e0ed8-7531-44a4-bd64-2b246291c600"));
    }

    public static String getSignature(String username, String password, String timestamp, String key){
        return hmac256_thenBase64(username + sha1_thenBase64(password) + timestamp, key);
    }
     
    private static String sha1_thenBase64(String s){
        try {
            MessageDigest md = MessageDigest.getInstance("SHA-1");
            byte[] bytes = s.getBytes(("UTF-8"));
            md.update(bytes);
            byte[] digest = md.digest();
            String hash = (new sun.misc.BASE64Encoder()).encode(digest);
            return hash; 
        } catch(Exception e) {

        }
        return null;
    }

    private static String hmac256_thenBase64(String s, String key){
        try {
            Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
            SecretKeySpec secret_key = new SecretKeySpec(key.getBytes(), "HmacSHA256");
            sha256_HMAC.init(secret_key);
            String hash = (new sun.misc.BASE64Encoder()).encode(sha256_HMAC.doFinal(s.getBytes()));
            return hash; 
        } catch(Exception e) {

        }
        return null;
    }
}

<?php
$auth = base64_encode(pack('H*', hash_hmac('sha256', 'UserName' . base64_encode(pack('H*', sha1('Password'))) . '1397500408', '617e0ed8-7531-44a4-bd64-2b246291c600')));
?>


The following is a sample request using the Timestamp and Authorization headers:

HTTP Request

POST /rest/system/status/secure-echo HTTP/1.1
Content-Type: application/json; charset=utf-8
UserName: UserName
Timestamp: 1397500408
Authorization: /pO71xQDqtAyMi9KOAzg4zUlNOhoFvROo4ZZp0GDqLE=
Host: sandbox.api.gnsvc.com
Content-Length: 37
Accept-Encoding: gzip, deflate
AdvancedErrorCodes: True

Body


Use the form below to ensure you are generating the correct Authorization signature in your code.

UserName:
Password:
ClientApplicationSecret:
Timestamp: