Authentication

The SO API uses HTTP Basic to authorize requests. Your unique Store ID (STO-#####) and API Key, found in the Seller Dashboard, are used to create the Authorization header. Additionally, the Accept and Content-Tye headers are required to be included with certain requests. You can also specify the API Version you are using with the header 'SO-Ver', this header is not required but we suggest using it to ensure your requests are reaching the correct version.

HTTP Basic Authorization

HTTP Basic Authorization uses a username and password that are encoded and passed with the request with the Authorization header. The username and password should be Base-64 encoded. The specifics of encoding the header will vary based on which programing language you are using, but the header should be formed as follows.

"Authorization" : "Base 64 encoded(username:password)"

How this header is created and passed will vary from language to language, but some examples are shown below.

JavaScript Request Example

let xhttp = new XMLHttpRequest();
let token = 'Basic ' + btoa('STO-123' + ':' + '123456')
xhttp.onreadystatechange = function() {
    if (this.readyState == 4 && this.status == 200) {
       let res = JSON.parse(this.responseText);
       document.getElementById("app").innerHTML = res.status;
   }
};
xhttp.open("GET", "https://api.subscriptionsonly.com/1.0.0/add-ons", true)
xhttp.setRequestHeader("Authorization", token);
xhttp.setRequestHeader("Accept", "application/json");
xhttp.send()

Creating the Authorization header with JavaScript In the example above the encoding is handled in the token variable. In JavaScript btoa() is used to Base 64 encode a string.

PHP cURL Request Example

$token = 'STO-123' . ':' . '123456';
$ch = curl_init();
curl_setopt_array(
    $ch,
    array(
        CURLOPT_URL => $url,
        CURLOPT_HTTPAUTH => CURLAUTH_BASIC,
        CURLOPT_HTTPHEADER => array(
            "Accept: application/json",
            "SO-Ver: 1.0.0"
        ),
        CURLOPT_USERPWD  => $token,
        CURLOPT_RETURNTRANSFER => true
    )
);

Adding the Authorization header to a PHP cURL request

In the PHP example using PHP cURL the string is created with the $token variable, but encoding is handled with CURLOPT_USERPWD => $token We set the option CURLOPT_HTTPAUTH to CURLAUTH_BASIC and the appropriate encoding is applied.

Accept Header

The Accept header is required by the API to process requests. If the Accept header is not included a 406 Not Acceptable response will be returned. Currently, the SO API only supports JSON responses, your accept header should be set to application/json. This header is required for all request types.

Accept: application/json

Content-Type Header

The Content-Type header is required for POST and PUT requests to be processed. Currently, the SO API only supports data sent as JSON and the Content-Type header should be set to application/json. If this header is incorrect a 412 Precondition Failed response will be sent.

Content-Type: application/json

SO-Ver Header

The SO-Ver header is an optional header that can be included with all requests. This header informs the API which version of the API you are intending to use. The version is also passed in the URL, but including the SO-Ver header could prevent errors in processing if you submit an invalid version in the URL.

SO-Ver: #.#.#

Use of this header is suggested to ensure you are interacting with the correct API version.