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