Oauth

Instructions for writing a ShopSite OAuth Application. This will walk through how to get an access token and how to use it.

Note:

If you plan to implement OAuth in PHP, we've created a pair of files that can be used to accelerate your development. The first, oauth.php, is an OAuth module that can be plugged directly in to your custom PHP script. The second, oauth_tester.php, contains examples of how to use the module with ShopSite. The zip file containing these files can be downloaded here:
OAuth_PHP.zip

Create Application in ShopSite

In order to make Download/Upload requests to ShopSite that is using User Logins you need to setup an Application to get credentials for the request. To do this follow these steps:

  1. Go to Utilities > Applications in the back-office
  2. Click "Add 3rd-Party App"
  3. Enter the Application Name
  4. Select the appropriate access permissions
  5. Click "Next"
  6. This will show the credentials for the Application
Save these credentials in the application you are writing. Be sure to save the Secret Key securely encrypted to avoid security problems. To view or change any Application's credentials in the future just select the Application from the list and click "Edit".

Get Authorization

Make the request

Send a POST request to the Authorization URL with the parameters: grant_type, code, client_credentials, and signature.

Here is a PHP example: 

 $nonce = mt_rand(10000000,99999999);
 $credentials = base64_encode("$clientid:$nonce");
 $signature = base64_encode(has_hmac("sha1", $credentials, $secretkey, true));
 $request = "grant_type=authorization_code"
           ."&code=$auth_code"
           ."&client_credentials=$credentials"
           ."&signature=$signature";
 
 $length = strlen($request);
 
 $ch = curl_init();
 curl_setopt($ch, CURLOPT_URL, $auth_url);
 
 curl_setopt($ch, CURLOPT_HTTPHEADER, array(
   "Content-Type: application/x-www-form-urlencoded", 
   "Content-Length: $length"
 ));
 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
 curl_setopt($ch, CURLOPT_POST, true);
 curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
 
 $json = curl_exec($ch);
 curl_close($ch);
Handle the response

The response will be JSON object with the access token and URLs. The expiration is the number of seconds until the token expires. This expire time will always be 30 seconds and it is really just used for one transaction. Here is a sample response: 

{
   "access_token": "MTYwNjg2NTc2N3xleGFtcGxlfDF8VGVzdHw3Njl8",
   "token_type": "MAC",
   "expires_in": 30,
   "download_url": "https://store.example.com/cgi-bin/sc/db_xml.cgi",
   "upload1_url": "https://store.example.com/cgi-bin/sc/dbupload.cgi",
   "upload2_url": "https://store.example.com/cgi-bin/sc/dbmake.cgi",
   "publish_url": "https://store.example.com/cgi-bin/sc/generate.cgi"
}

Use the authentication token in a request

To use the Access token in a request for an upload or download request a complicated signature needs to be calculated. First, a new unique nonce will need to be created and the current UNIX timestamp stored in a variable. The signature is a list of tokens on their own lines then SHA1 HMAC encrypted using the Secret key from the Applications credentials. The format for the signature is: 
{Access token from authorization}
{timestamp}
{nonce}

{Request Method (POST)}
{Request domain of the URL in the Authorization response}
{Request Port (usually 443 for secure requests)}
{Request path of the URL in the Authorization response}
{Alphabetically sorted list of URL encoded parameters}
Note the blank line between the the nonce and the request method and that the signature ends with a newline. Here is an example of the signature before encrypting for an order download: 
MTYwNjg2NTc2N3xleGFtcGxlfDF8VGVzdHw3Njl8
1607027431
a882ebb44e64

POST
store.example.com
443
/cgi-bin/sc/db_xml.cgi
clientApp=1
dbname=orders
startdate=11%2F01%2F2020
version=14.0
The parameters for the authentication are token (the access token from the authorization response), timestamp, nonce, and signature. The rest of the parameters are described here for Order Download and here for Uploading, Downloading, and Publishing other data.

Here is a continuation of the above PHP example where $data is an array of the needed request parameters: 

 $json = json_decode($json, true);
 $nonce2 = mt_rand(10000000,99999999); # nonce for download request
 $timestamp = time();                  # UNIX time
 $token = $json['access_token'];
 $endpointurl = $json['download_url'];
 $url_stuff = parse_url($endpointurl);
 $endpoint = $url_stuff['path'];
 $domain = $url_stuff['host'];
 $protocol = $url_stuff['scheme'];
 if(isset($url_stuff['port']))
   $port = $url_stuff['port'];
 else if(strcasecmp($protocol, 'https') == 0)
   $port = 443;
 else
   $port = 80;
 
 # put the array back into an MAC-compatible string
 $imploded = "";
 ksort($data);
 foreach($data as $k=>$v) {
   $imploded .= "$k=" . rawurlencode($v) . "\n";
 }
 $imploded = trim($imploded,"\n");
 $macdigest = "$token\n$timestamp\n$nonce2\n\nPOST\n$domain\n$port\n$endpoint\n$imploded\n";
 $macdigesthash = hash_hmac("sha1", $macdigest, $secretkey, true);
 $signature2 = base64_encode($macdigesthash);
 
 $data['signature'] = $signature2;
 $data['token'] = $token;
 $data['timestamp'] = $timestamp;
 $data['nonce'] = $nonce2;
 
 $db_request = "";
 foreach ($data as $k=>$v) {
   $db_request .= "$k=$v&";
 }
 $db_request = trim($db_request, "&");
 
 $ch = curl_init();
 curl_setopt($ch, CURLOPT_URL, $endpointurl);

 curl_setopt($ch, CURLOPT_POST, true);
 curl_setopt($ch, CURLOPT_POSTFIELDS, $db_request);
 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
 
 $downloaddata = curl_exec($ch);
 curl_close($ch);
ShopSite Help and Resource Center
Last updated: December 04, 2020
Give Feedback

ShopSite Shopping Cart Software