REST API Authentication

 

The Zanox REST authentication implementation includes the connect ID, secured mhash key (signature) and the timestamp inside the HTTP Header. The REST Hash signature transmission is based onto the RFC2616 for HTTP Digest Access Authentication specifications. Alternatively, it is possible to provide the timestamp, nonce and signature as URL query parameters, without the header.

Public resources - auth with connect ID

For public resources, it is enough to provide the connect ID as query parameter:

http://api.zanox.com/xml/2011-03-01/programs?connectid=802B8BF4AE99EBE00F41

or as "Authorization" header:

GET /xml/2011-03-01/programs HTTP/1.1
Host: api.zanox.com
Authorization: ZXWS 802B8BF4AE99EBE00F41

Private resources - auth with signature

The actual building of the signature is taken from the RFC2104 specification. The signature is built by applying a keyed-HMAC (Hash Message Authentication Code) algorithm to the UTF-8 encoded StringToSign. The secret key has to be provided as a parameter to the keyed-HMAC method.

Here is the simple explanation of how to generate a signature.

Signature = Base64( HMAC-SHA1( UTF-8-Encode( StringToSign ), secretKey ) );



The StringToSign consists of a couple of elements that are concatenated:

HTTP-Verb + URI + timestamp + nonce

HTTP Verb - GET, POST, PUT or DELETE;
URI - exclude return format and API version date, include path parameters.  

For example, for the URL http://api.zanox.com/json/2011-03-01/reports/sales/date/2013-07-20,
the URI would be /reports/sales/date/2013-07-20.

Timestamp - in GMT, format "EEE, dd MMM yyyy HH:mm:ss";
Nonce - unique random string, generated at the time of request, valid once, 20 or more characters

 

To successfully authenticate, connect ID, timestamp, nonce and signature have to be passed either as URL query parameters or as HTTP Headers. Please note that it is only necessary to do one or the other, you do not have to do both.

When authenticating via the URL, the query parameter names are connectid, date, nonce and signature respectively (line breaks added for clarity):

http://api.zanox.com/xml/2011-03-01/reports/sales/date/2013-07-20
?connectid=802B8BF4AE99EBE00F41
&date=Thu, 15 Aug 2013 15:40:01 GMT
&nonce=7145C63A5353392FD3A11C67EC5B42A7
&signature=AcMW31Nk1RPf3uy1IeHi73/pqjE=

One thing to be aware of when authenticating with URL query parameters is that sometimes the signature will contain a + symbol, which will be interpreted by the browser as a space character.  Therefore it is also necessary that you replace the + symbol with %2B in the signature string before submitting.

As headers, the authentication values must be set in the following way:

Authorization: ZXWS connectid:signature
Date: timestamp
nonce: nonce

 

Example

Connect ID: 802B8BF4AE99EBE00F41
Secret Key: fa4c0c2020Aa4c+ab9Ea0ec8d39E06/df2c5aa44
API Method: GET Sales for the date 2013-07-20

1. Generate nonce and timestamp

Nonce: 17811FEFBA7448CE848327F835729AA2
Timestamp: Thu, 15 Aug 2013 15:56:07 GMT

2. Concatinate HTTP Verb, URI, timestamp and nonce to create StringToSign

GET/reports/sales/date/2013-07-20Thu, 15 Aug 2013 15:56:07 GMT17811FEFBA7448CE848327F835729AA2

3. Hash the StringToSign using the secret key as HMAC parameter

Signature: N4RPYDY1aUjciVm32pCJ82FVvuk=

4. Add information to request headers

Authorization: ZXWS 802B8BF4AE99EBE00F41:N4RPYDY1aUjciVm32pCJ82FVvuk=
Date: Thu, 15 Aug 2013 15:56:07 GMT
nonce: 17811FEFBA7448CE848327F835729AA2

5. GET http://api.zanox.com/json/2011-03-01/reports/sales/date/2013-07-20 with above headers

Check out a working example code written in Java.

Here is some example code written in PHP.