Reference Guide - Authentication

From SRP API Docs

Authentication

Only authenticated users can access StructuredRetailProducts.com API features.

This documentation describes how the authentication process works on StructuredRetailProducts.com.

Registration

During the registration process clients are issued a PublicApiKey (a key which can be accessed by anyone) and PrivateApiKey (a private key, which only the registered user has access to). The two keys work together, so a message scrambled with the private key can only be unscrambled with the public key and vice versa. If you have purchased a licence to the SRPFeed or the SRPUltraFeed but have not received a PrivateApiKey and a PublicApiKey, please Contact Us.

Protocol

For extra security all StructuredRetailProducts.com API requests must be made using HTTPS transfer protocol. Requests made over HTTP transfer protocol will not be accepted and 404 response code will be sent.

Signing and Authenticating REST Requests

Every single request made to the StructuredRetailProducts.com API must be signed and authenticated. Our uses a custom HTTP scheme based on a keyed-HMAC (Hash Message Authentication Code) for authentication. To authenticate a request, you first concatenate selected elements of the request to form a string. You then use your Private Api Key to calculate the HMAC of that string. Informally, this process is called "signing the request," and the output of the HMAC algorithm is called the "signature" because it simulates the security properties of a real signature. Finally, you add this signature as a parameter of the request, using the syntax described in this section.

When the system receives an authenticated request, it fetches your Private API Key from our database, and uses it in the same way to compute a "signature" for the message it received. Then it compares the provided signature with the computed one. If the two signatures match the system grants the access. If the two signatures do not match the request is dropped and the system responds with an error message.

The Authorization Header

SRP authorization type is used. The StructuredRetailProducts.com API uses the standard HTTP Authorization header to pass authorization information. The authorization header has the following form:

Authorization: SRP PublicApiKey:Signature:Timestamp

The HMAC-SHA1 algorithm takes as input two byte-strings: a key and a message. For the StructuredRetailProducts.com API Request authentication use your PrivateApiKey as the key and the UTF-8 encoding of the StringToSign as the message. The output of HMAC-SHA1 is also a byte string, called the digest. The Signature request parameter is constructed by Base64 encoding this digest.

Building "StringToSign"

StringToSign consists of concatenated selected parameters from the request in UTF8 encoding. All parameters are single space (" ") separated.

The selected parameters are:

  1. Type - Uppercased request type. Possible values are GET POST PUT DELETE
  2. URI - HTTP Request-Uri
  3. Length - HTTP Content-Length value
  4. MD5 - HTTP Content-MD5 value
  5. Timestamp - Timestamp in UTC when request is made

StringToSign:

{Type} {URI} {Length} {MD5} {Timestamp}

Sample of StringToSign:

POST /v1/products 254 d131dd02c5e6eec4693d9a0698aff95c 1328092594

Please note that GET requests don't have content - in this instance Content-Length and Content-MD5 are NULL values, but the separators are still kept (3 spaces between URI and timestamp):

GET /v1/products   1328092594

Timestamp Requirement

The same Timestamp must be included in HTTP Authentication header and in StringToSign. It must be in UTC timezone. It must be within 15 minutes of the StructuredRetailProducts.com API system time when the request is received. If not, the request will fail with the Request time is too skewed error status code. The intention of these restrictions is to limit the possibility that intercepted requests could be replayed by an adversary.

Authentication examples (GET methods)

Client keys:

PublicApiKey: PJ1TZHT75PHJHNA5S2TZHJFXBG3JNW1P
PrivateApiKey: Jx1qfZA1OLgj5s6A8wzHI7T9aHb2b1zHItPATXPPJNwHBx17HZjKhnoLGJFX7t75

Client Timestamp:

1328092781

Request:

GET /v1/products?market=MK0012 HTTP/1.1
Content-Length 
Content-MD5 

Or request can be without Content-Length and Content-MD5 because they are NULL values :

GET /v1/products?market=MK0012 HTTP/1.1

StringToSign:

GET /v1/products?market=MK0012   1328092781

Signature (TODO: provide actual signature, cause this is dummy):

U9YU+H6hn81pp8KuRHw+rNtB9k0=

Authorization header (TODO: provide actual auth header, cause this is dummy):

SRP PJ1TZHT75PHJHNA5S2TZHJFXBG3JNW1P:U9YU+H6hn81pp8KuRHw+rNtB9k0=:1328092781

Final request with Authorization header (TODO: provide actual auth header, cause this is dummy):

GET /v1/products?market=MK0012 HTTP/1.1
Authorization SRP PJ1TZHT75PHJHNA5S2TZHJFXBG3JNW1P:U9YU+H6hn81pp8KuRHw+rNtB9k0=:1328092781


On successful authentication HTTP Status Code 200 will be sent.

Authentication examples (POST, PUT methods)

Client keys:

PublicApiKey: PJ1TZHT75PHJHNA5S2TZHJFXBG3JNW1P
PrivateApiKey: Jx1qfZA1OLgj5s6A8wzHI7T9aHb2b1zHItPATXPPJNwHBx17HZjKhnoLGJFX7t75

Client Timestamp:

1328092781

Request:

POST /v1/products?market=MK0012 HTTP/1.1
Content-Length 257
Content-MD5 e4693df9ec5136eec8af95c1dd029a06

StringToSign:

POST /v1/products?market=MK0012 257 e4693df9ec5136eec8af95c1dd029a06 1328092781

Signature:

U9YU+H6hn81pp8KuRHw+rNtB9k0=

Authorization header:

SRP PJ1TZHT75PHJHNA5S2TZHJFXBG3JNW1P:U9YU+H6hn81pp8KuRHw+rNtB9k0=:1328092781

Final request with Authorization header:

POST /v1/products?market=MK0012 HTTP/1.1
Content-Length 257
Content-MD5 e4693df9ec5136eec8af95c1dd029a06
Authorization SRP PJ1TZHT75PHJHNA5S2TZHJFXBG3JNW1P:U9YU+H6hn81pp8KuRHw+rNtB9k0=:1328092781


On successful authentication HTTP Status Code 200 will be sent.

Request Signing Problems

When request authentication fails, the system responds with HTTP Status Code 401 and an XML error document. The document tells you exactly what request parameters were used on the server to build "StringToSign" element. This is meant to help developers diagnose the problem.

For general errors please also see Debugging Error section.

XML error document

<?xml version="1.0" encoding="UTF-8"?>
<products>
  <status code="401">Authentication failure</status>
  <authentication>
    <type></type>
    <uri></uri>
    <content_length></content_length>
    <content_length_actual></content_length_actual>
    <content_md5></content_md5>
    <content_md5_actual></content_md5_actual>
    <timestamp></timestamp>
    <timestamp_actual></timestamp_actual>
    <allowed_time_skew></allowed_time_skew>
  </authentication>
</products>