Examples

Authentication

The examples assume that an access_token has been obtained and the client is ready to call the Merchant API. See Authentication for more information.

Clients should keep track of the expiration time and request a new access_token when necessary.

Ruby example:

require 'rack/oauth2'
require 'hyperresource'

API_ROOT = ENV['API_ROOT'] # https://merchant.test.clearhaus.com
CLIENT_ID = ENV['CLIENT_ID']
CLIENT_SECRET = ENV['CLIENT_SECRET']
AUDIENCE = ENV['AUDIENCE'] # https://merchant.test.clearhaus.com

# Init API client
api_client = HyperResource.new(
  root: API_ROOT, 
  headers: { 'Content-Type' => 'application/json' }
)

# Retreive OAauth2 token endpoint
oauth_endpoint = api_client.get.links['oauth2-token'].href

# Init OAuth2 client
oauth2_client = Rack::OAuth2::Client.new(
  identifier: ENV['CLIENT_ID'], 
  secret: ENV['CLIENT_SECRET'], 
  token_endpoint: oauth_endpoint
)

# Use one of the supported OAuth2 grants
# Client Credentials grant
token_response = oauth2_client.access_token!(audience: AUDIENCE)

# Obtain access token and expiration time
# Clients should keep track of the expiration time and 
# request a new access_token when necessary
access_token, expires_in = token_response.access_token, token_response.expires_in

# Update API client to use access_token
api_client.config(API_ROOT => { 'headers' => { 'Authorization' => "Bearer #{access_token}" } })

# Retrieve authenticated root
api_client.get.body
=>
{
  "_links" => {
    "self" => {
      "href" => "https://merchant.test.clearhaus.com"
    },
    "oauth2-token" => {
      "href" => "https://merchant.test.clearhaus.com/oauth/token"
    },
    "ch:applications" => {
      "href" => "https://merchant.test.clearhaus.com/applications{?query,page,per_page}",
      "templated" => true
    },
    "curies" => [
      {
        "href" => "https://developer.clearhaus.com/rels/{rel}",
        "templated" => true,
        "name" => "ch"
      }
    ]
  }
}

# Start calling the Merchant API