HMAC is used for stateless transactions with the API. You will not have to make a request to the login route because the API public and private key don't change. The login route is specifically for JWT authentication.

HMAC authentication is a complicated authentication method so if you are trying to get up and running quick then you can try out JWT.

Note

If you do not have your API key and private key then please contact your Moby point of contact.

Preface

Throughout this document there will be references to variables like this {algorithm}. This is just a placeholder name for a value. When ever you see one of these place holders in the documentation you should replace it with your own value. This is a list of those variables and a description of what they are and what you should replace them with in your own call.

Placeholder Name	Description
{algorithm}	The hashing algorithm that you used to hash the contents of the request
{hash}	The hash that was created when the contents of the request were hashed. Please See Hashing
{apiKey}	The public API key given to you by moby
{privateKey}	The private API key given to you by moby that is used for hashing the request
{timeStamp}	The time of the request in ISO 8601 format. Please use GMT. Schema: YYYY-MM-DDThh:mmTZD. ex. 2016-11-23T16:48:35.627Z

All HMAC authenticated routes require these parameters to be in your request. Pay close attention to the location of the parameters.

Request Parameter Name	Location	Value
Authorization	Header	{algorithm} {hash}
apiKey	Header	{apiKey}
timeStamp	Body for Post / Url for GET	{timeStamp}

Synopsis

HMAC is a method for authentication not encryption. To perform an HMAC request you must hash the request and store the hash in the Authorization header. An apiKey must also be provided in the header for recognition of who is trying to authenticate. The timeStamp is also required so that the api can prevent timing attacks. The timeStamp must be within 5 minutes of current GMT. read an article about it here.

Hashing

What to hash?

Depending if the request is a GET or a POST we hash different content.

GET

You must hash the url not including the baseurl.

Example:

GET /api/validation?sortBy=uploadDate&timeStamp=2016-11-23T19%3A26%3A18.407Z HTTP/1.1
Host: staging.gotmoby.com
Authorization: {algorithm} {hash}

we would only hash /validation?sortBy=uploadDate&timeStamp=2016-11-23T19%3A26%3A18.407Z

POST

You must hash the raw post body.

Example:

POST /api/validation HTTP/1.1
Host: staging.gotmoby.com
Content-Type: application/x-www-form-urlencoded
Authorization: {algorithm} {hash}

uniqueId=test-hhxnln&name=Test+Person&postBackUrl=http%3A%2F%2Fstaging.gotmoby.com%2Fapi%2F%7B%7BpostBackUrl%7D%7D&isTest=false&timeStamp=2016-11-23T19%3A26%3A18.407Z

we will only hash

uniqueId=test-hhxnln&name=Test+Person&postBackUrl=http%3A%2F%2Fstaging.gotmoby.com%2Fapi%2F%7B%7BpostBackUrl%7D%7D&isTest=false&timeStamp=2016-11-23T19%3A26%3A18.407Z

How to Hash?

These are the steps that will be taken in PHP, In order to repeat the hashing process in a different language you must look up the HMAC hashing techniques in your language of choice.

1. make sure the timeStamp parameter is in the contents that you are hashing.
2. Hash the contents using using HMAC with the algorithm you would like to use. Make sure that you get the binary output from the HMAC hash.
3. After you have the binary output, base64 encode it and place it in the {hash} location in the Authorization header.
4. Use the private key to perform the hash.
5. Place the algorithm that you used in the {algorithm} location

View Supported Hashing Algorithms

Example Code:

 $hash = base64_encode( // we base64 encode the binary output from HMAC
   hash_hmac( 'sha1', // the algorithm used for the hashing
     '/drivers-licenses?perPage=30&timeStamp=2016-11-23T18:54:37.991Z', // for GET request we use the url without the baseUrl with the leading slash
     '9c7dbe349e13d25ff67f00ba9fc383d2', // the private key matching the account. The private key will never be sent accross the wire
     true // this argument set to true means that the HMAC will output binary
  ));

Example HMAC Requests

Example GET Request using HMAC

 GET https://staging.gotmoby.com/api/drivers-licenses?perPage=30&timeStamp=2016-11-23T18:54:37.991Z HTTP/1.1
   Host: staging.gotmoby.com
   Authorization: sha1 OxtHeHzKEVsTrbzL0Lw00dj/5CQ=
   apiKey: a396982d5a4116abc3453564fe346ed9

Example POST Request using HMAC

 POST https://staging.gotmoby.com/api/drivers-licenses HTTP/1.1
   Host: staging.gotmoby.com
   Authorization: sha1 NPjZr810EhD3gcn3k36H++4A82U=
   apiKey: a396982d5a4116abc3453564fe346ed9
   Content-Type: application/x-www-form-urlencoded

timeStamp=2016-11-23T19%3A26%3A18.407Z&name=Test+Person&postBackUrl=test&uniqueId=my_test_id

Here is that exact PHP code used to generate the hash for that request

$hash = base64_encode( // we base64 encode the binary output from HMAC
  hash_hmac( 'sha1', // the algorithm used for the hashing
  'timeStamp=2016-11-23T19%3A26%3A18.407Z&name=Test+Person&postBackUrl=test&uniqueId=my_test_id', // for a POST request we hash the raw body. be sure content type is set correctly or the server may hash it differently
  '9c7dbe349e13d25ff67f00ba9fc383d2', // the private key matching the account. The private key will never be sent across the wire
  true // this argument set to true means that the HMAC will output binary
));

Testing

When testing HMAC please use the HMAC test routes provided in the postman documentation for they do not provide any operations

Test GET

Test POST