API Documentation

This service is in BETA. For access please Fill out the application

CONTENTS
RESOURCES
MACROS
VERBS
REPORTS
RESEARCH API

Authentication

SLAPI uses the oAuth2 standard for authentication


Overview

Sample clients


Register Your Application

To register a new application, please Contact Us Directly to obtain your client_id and client_secret

Obtain an Access Token

There are several ways to obtain an access token, depending on where your application will run

Web Applications

The OAuth 2.0 Three-Legged allows your application to access SLAPI on behalf of a specific user. Your application needs to perform two specific steps:

Google describes the process pretty well in their documentation

STEP 1

Generate a authorization request and send the user to the Seller Labs server. If using an OAuth library, you'll just need to enter the authorization endpoint as https://secure.sellerlabs.com/oauth2/auth. If you are generating the request manually, it will look something like this:

    https://secure.sellerlabs.com/oauth2/auth
        ?redirect_uri=http%3A%2F%2Fwww.yourapp.com%2Fauthenticate
        &type=web_server
        &client_id=[[YOUR CLIENT ID]]
        &response_type=code
        &scope=[[SPECIFIC PERMISSIONS REQUESTED]]
        &state=[[SESSION INFORMATION TO IDENTIFY YOUR USER]]

When the user arrives at that page, they will need to log in to their Seller Labs account, then will be prompted to authorize your application for the specific permissions that were requested

Upon successful authentication at Seller Labs, the user will be redirected back to the redirect_uri specified in the request with a &code= parameter that includes an authorization code. This authorization code is only valid for a few seconds and must be exchanged immediately for an Access Token

STEP 2

Next, you need to exchange the authorization code received in the URL with an actual token. Most OAuth libraries should have a function that just requires the authorization code from Step 1 and will return the actual token. If constructing the request yourself, the URL will look something like:

    https://secure.sellerlabs.com/oauth2/token
        ?client_id=[[YOUR CLIENT ID]]
        &client_secret=[[YOUR CLIENT SECRET]]
        &grant_type=authorization_code
        &response_type=token
        &code=[[THE AUTHORIZATION CODE FROM STEP 1]]

The response from that will contain an access_token, the length of time that it is valid, and a refresh_token

Javascript Applications

Implimentation in a Javascript is similar, but noticibly different from the typical three-legged approach. Again their are two specific steps that your application needs to perform.

Google describes the process pretty well in Their Documentation

STEP 1

Request an access Token using response_type=token

https://secure.sellerlabs.com/oauth2/auth
    ?redirect_uri=http%3A%2F%2Fwww.yourapp.com%2Fauthenticate
    &response_type=token
    &client_id=[[YOUR CLIENT ID]]
    &state=[[SESSION INFORMATION TO IDENTIFY YOUR USER]]
    &scope=[[SPECIFIC PERMISSIONS REQUESTED]]

When the user arrives at that page, they will need to log in to their Seller Labs account, then will be prompted to authorize your application for the specific permissions that were requested

Upon successful authentication at Seller Labs, the user will be redirected back to the redirect_uri specified in the request with a #token= parameter in the URL. The token can be parsed out of that hash in the URL. The Javascipt code to read the authorization code may look something like this:

// First, parse the query string
var params = {}, queryString = location.hash.substring(1),
    regex = /([^&=]+)=([^&]*)/g, m;
while (m = regex.exec(queryString)) {
  params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
}

STEP 2

Validate the token: Hit https://api.sellerlabs.com/oauth2/tokeninfo with the token, and validate that the client_id in the response is your client_id

Mobile Applications

Approved clients may authenticate a user with with their username and password.

$ curl -u ClientId:ClientSecret https://secure.sellerlabs.com/oauth2/token
    -d 'grant_type=password&username=user%40domain.com&password=password'

Access the API resources using your access token

Send the access token in the HTTP Authentication header

GET /v1/whoami HTTP/1.1
Host: api.sellerlabs.com
Authorization: Bearer [[TOKEN GOES HERE]]


Sample Code

Sample Implementation in PHP

This sample uses the PHPoAuthLib class from GitHub

Download SellerLabs.php which is our service provider code for use with this class

    use OAuth\Common\Storage\Session;
use OAuth\Common\Consumer\Credentials;

require_once 'SellerLabs.php';

$uriFactory = new \OAuth\Common\Http\Uri\UriFactory();
$currentUri = $uriFactory->createFromSuperGlobalArray($_SERVER);
$currentUri->setQuery('');

// Use the default 'Session' storage engine which saves the token in a PHP Session
$storage = new Session(false, 'slapi_oauth');

$credentials = new Credentials(
    'your_client_id',
    'your_client_secret',
    $currentUri->getAbsoluteUri()
);

$serviceFactory = new \OAuth\ServiceFactory();

$slapi = $serviceFactory->createService('SellerLabs', $credentials, $storage, array(''));

$slapi->setOauthBase("https://secure.sellerlabs.com/oauth2/");
$slapi->setBaseUrl("https://api.sellerlabs.com/v1/");

// User is redirected back here with &code that contains an authorization code
//    that we excange for a valid access token
if (!empty($_GET['code'])) {

    try {
        $slapi->requestAccessToken($_GET['code']);
        echo "Your session has been validated";
        // Now you can do something interesting with $slapi
        $response = $slapi->request('/whoami', 'GET');
        $whoami = json_decode($response, true);
        echo "You are logged in as {$whoami['user']['email']}\n";
    } catch (Exception $e) {
        echo "An Error Occurred while validating your access code\n";
        echo $e->getMessage();
    }
    exit;
}

try {
    $raw = $slapi->request("/orders", 'GET');
    $object = json_decode($raw,true);
    print_r($object);

} catch (Exception $e) {
    // Other exceptions may be caught here
    $url = $slapi->getAuthorizationUri(array('state' => 'abc123'));
    echo "oAuth Authentication required. .. Click ";
    echo <a href=\"{$url}\">HERE</a>\n";exit;
}