Authentication

All of the calls to the REST API required authentication.  This ensures that data is protected and server resources conserved.  In order to properly authenticate, each REST call must contain two parameters:

1. Access Key - Each call must contain an access key as a parameter on the URL string.  The key value for the access key parameter is "access_key".  The access key is not private and is used to identify the caller to the server.  Your access key is available under the "Access Identifiers" section of your SMB console.
2. Signature - Each call must contain a signature as a parameter on the URL string.  The key value for the signature parameter is "signature".  The signature is a SHA1 encoded hash that securely authenticates the caller on the server.  The signature must be generated before each call using a secret code.  Because the secret code is used to generate the SHA1 hash (one way hash) the code is secure and private.  Your secret code is available under the "Access Identifiers" section of your SMB console.  You should never share your secret code.  For more information on generating a signature using a secret code see below.

Generating a Signature

To properly generate a signature for a call to the REST API you first need your secret code.  The secret code, along with the URL string for the request you are making are combined and encoded to form the signature for your API call.  As an example let's say you wanted to list the spaces currently on your SMB system.  For the example our access key will be "123456789" and our secret code will be "abcdefghi".  The URL string to list the spaces on an SMB system would be as follows:

http://demo.saffronmb.ws/spaces?access_key=123456789

Before generating a hash for the signature you will need to concatenate the URL string with your secret code.  Once we concatenate the two the string would be as follows:

http://demo.saffronmb.ws/spaces?access_key=123456789abcdefghi

Then you need to generate a SHA1 encoded hash of that string to form the signature for the call.  After encoding, the signature for this call would be as follows:

790b9042bad5a464bad6548164b1aa184180483f

After calculating the signature you then need to add it as a parameter to the call you make to the SMB server.  The actual call you would make to the server would be as follows:

http://demo.saffronmb.ws/spaces?access_key=123456789&signature=790b9042bad5a464bad6548164b1aa184180483f

Getting a New Secret Code

If you believe that your secret code has been compromised you can generate a new one under the "Access Identifiers" section of the SMB console.  All future requests to the REST API will need to use the new secret code.

<< Back to Getting Started