KIBO OMS DOCUMENTATION

Authentication

This guide applies to all REST-based APIs that are secured by OAuth 2. Any calls made to Kibo APIs will have to first perform this OAuth 2 process to authenticate and receive an access token.

Prerequisites

  • An issued API Key
  • An issued Client Secret Key

Both the API Key and Client Secret Key are issued by an account manager.

Acquire an API Token

The API token (or access token) is provided by the OAuth server and used in each API call to validate the authenticity of the user. There are two steps to this process: generating credentials and requesting the token.

 

Generate Credentials

Encode the API and Client Secret keys in Base64 with the format {api key}:{secret key}.

For example, encoding using a Mac or Linux terminal would be done with the command “echo -n {api key}:{secret key} | base64”. The resulting credentials should look something like this:

cmRzOHlrY2JlZGJmYmR8bjRuJTJiZ3lyOjNEcWJ0VjJRZHVWcjVTSlljTkNSbXA1OA==

 

Request the Token

API tokens are valid for a limited time – normally 1 hour – which is defined in the response from the OAuth server. It is the user’s responsibility to acquire a new token before the expiration time, or attempt to acquire a new token should they receive a 401 (Unauthorized) or 403 (Forbidden) HTTP status code. Make every possible attempt to reuse tokens for subsequent API calls. Acquiring a new token for each call will significantly impact performance.

To build the token request, first select the appropriate URL for the OAuth server.

EnvironmentURL
Livehttps://auth.shopatron.com/oauthserver/oauth2/token
Staginghttps://authstaging.cloudatron.com/oauthserver/oauth2/token
Developmenthttps://authdev.cloudatron.com/oauthserver/oauth2/token

Then, build off of that endpoint with the following request structure.

Request ElementContent
HTTP Request HeaderContent-Type: application/x-www-form-urlencoded
Authorization: Basic {generated credentials}
Accept: application/json
HTTP Request Bodygrant_type=client_credentials

This is what the full request should look like.

curl -H "Content-Type=application/x-www-form-urlencoded" -H "Authorization=Basic {generated credentials}"\
     -H "Accept=application/json" -X POST -d "grant_type=client_credentials" \
     https://auth.shopatron.com/oauthserver/oauth2/token

A successful response will provide an access token similar to this sample. Note that the “expires_in” value is represented in seconds.

  • Response Header: “Content-Type: application/json”
  • Response Object (JSON):
{
 "scope":"",
 "access_token":"a2853b04d0ff4b2999073938944078f",
 "token_type":"bearer",
 "expires_in":3600
}

Invoke a REST API

Now the keys are ready to be put to use.

Full Example Request

This example demonstrates how to combine authentication with a call to the API. Note how the token is included in the final GET request.

#!/bin/bash

# OAuth URL
OAUTH_URL="https://auth.shopatron.com/oauthserver/oauth2/token"

# Generate the credentials from the client id and secret key.
CLIENT_ID="{…}"
SECRET_KEY="{…}"
CREDENTIALS=$(echo -n $CLIENT_ID:$SECRET_KEY | base64)

# Use the credentials to get an api token.
CURL_RESULT=$(curl -sv -H "Content-Type: application/x-www-form-urlencoded" \
 -H "Authorization: Basic $CREDENTIALS" -X POST $OAUTH_URL \
 -d grant_type=client_credentials)
echo $CURL_RESULT
TOKEN=$(echo $CURL_RESULT | sed ’s/\"/ /g’ | awk {’print $7’})

# Invoke a GET request against the get location by location id API.
CURL_URL="https://integration.shopatron.com/api/v2/location/{…}"
curl -sv -H "API-Key: $CLIENT_ID" -H "Content-Type: application/json" \
 -H "Authorization: Bearer $TOKEN" -X GET $CURL_URL

Rates & Limits

Before looking at the full response, it’s important to note that each set of these keys is allotted a certain number of API calls defined on a per client basis. There exists a per second (QPS) and either a per hour or per day (Quota) limit. The immediate usage is returned in the header of each API response.

X-Plan-QPS-Allotted: 20
X-Plan-QPS-Current: 1
X-Plan-Quota-Allotted: 5000
X-Plan-Quota-Current: 2
X-Plan-Quota-Reset: Friday, January 29, 2016 7:00:00 PM GMT

Full Example Response

The response payload is extensive, but the HTTP response code “200 OK” that indicates the success of the call is easy to find. Also note where the rates and limits information is located within the header. The details from the API that were requested is at the end of the response.

* Trying 54.187.198.17…
* Connected to auth.shopatron.com (127.0.0.1) port 443 (#0)
* Server certificate: *.shopatron.com
* Server certificate: GeoTrust SHA256 SSL CA
* Server certificate: GeoTrust Primary Certification Authority - G3
> POST /oauthserver/oauth2/token HTTP/1.1
> Host: auth.shopatron.com
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Type: application/x-www-form-urlencoded
> Authorization: Basic …
> Content-Length: 29
>
* upload completely sent off: 29 out of 29 bytes
< HTTP/1.1 200 OK
< Content-Type: application/json
< Date: Wed, 10 Feb 2016 23:28:02 GMT
< Server: Apache-Coyote/1.1
< transfer-encoding: chunked
< Connection: keep-alive
<
* Connection #0 to host auth.shopatron.com left intact
{"scope":"","access_token":"…","token_type":"bearer","expires_in":3600}
* Trying 54.215.17.153…
* Connected to integration.shopatron.com (127.0.0.1) port 443 (#0)
* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
* Server certificate: integration.shopatron.com
* Server certificate: GeoTrust DV SSL CA - G4
* Server certificate: GeoTrust Global CA
> GET /api/v2/locale/ HTTP/1.1
> Host: integration.shopatron.com
> User-Agent: curl/7.43.0
> Accept: */*
> API-Key: {…}
> Content-Type: application/json
> Authorization: Bearer {…}
< HTTP/1.1 200 OK
< Cache-Control: no-cache
< Content-Type: application/json; profile="/api/v2/schema/location.json"
< Date: Fri, 29 Jan 2016 18:48:31 GMT
< Server: nginx
< Vary: Accept-Encoding
< X-Mashery-Responder: prod-j-worker-us-west-1c-65.mashery.com
< X-Plan-QPS-Allotted: 20
< X-Plan-QPS-Current: 1
< X-Plan-Quota-Allotted: 5000
< X-Plan-Quota-Current: 2
< X-Plan-Quota-Reset: Friday, January 29, 2016 7:00:00 PM GMT
< Content-Length: 502
< Connection: keep-alive
<
* Connection #0 to host integration.shopatron.com left intact
{ 
 "locationID":…,
 "retailerID":…,
 "name":"Location Name",
 "addressLine1":"address 1",
 "addressLine2":"",
 "addressLine3":"",
 "city":"San Luis",
 "state":"CA",
 "countryCode":"US",
 "postalCode":"93401",
 "contact":"Test Location",
 "contactPhone":"xxx-xxx-xxxx",
 "phone":"xxx-xxx-xxxx",
 "fax":"",
 "email":"test@test.com",
 "latitude":35.2742,
 "longitude":120.6631,
 "localSalesTax":0,
 "active":true,
 "shippingLocation":true,
 "taxableLocation":false,
 "mainLocation":false
}

 


Megan MayfieldOMS Dev: Authentication