Using OAuth

How to use OAuth to authenticate with the API

In order to use the MerchantOS API, you need an API key. Getting your API Key describes the process of getting a simple API key for using Basic Authentication with the MerchantOS API. OAuth allows you to get API keys for users in a much simpler and streamlined manner.

Overview

MerchantOS uses the OAuth 2 protocol for wrapping API Client authorization and authentication. OAuth 2 allows us to simplify the process the users must go through to grant a client access to their account via the API. Using the OAuth 2 protocol requires the following steps:

Register Your Client
Obtaining an Access Token
Making API Requests

Register Your Client

Before you can use OAuth you must register your client.
Visit the MerchantOS OAuth 2 API Client Signup page and enter the relivant information.

The Name field is what is shown to the user when they are redirected to MerchantOS to allow permission to your application. Ensure that it describes your application well enough that users will understand which application is asking for permission to their account.
The Client ID and Client Secret are used during the key exchange and authentication. Ensure that you keep your Client Secret is kept secure as is used to identify your application with MerchantOS. Your client ID and secret can be any combination of letters and numbers less than 256 characters each.
The Redirect URI is the location the user will be redirected back to after granting permission to your application. This URI will receive the needed temporary code to receive a permanent token.
Please fill out the rest of the contact information. This information will be used by MerchantOS to assess whether your client should be approved for API access.
Once you have filled our the Client Signup, MerchantOS will review your information and contact you for any more information and when your client is approved.

Obtaining an Access Token

An Access Token is the credential that allows you to access a MerchantOS account via the API. When you ask a user to authorize your application, in addition to your Client ID you must specify what permissions you are requesting. The following section discusses how to have your client authorized and how to receive your Access Token.

OAuth Endpoints

The following are the end points used to gain OAuth access to the MerchantOS API. The Client Registration is only used once to register your client with MerchantOS (or to update your client information). The authorization endpoint is where you will redirect clients to authorize your application for access to their account. The access token endpoint is used to convert the temporary token you receive from a successful authorization for a semi-permanent Access Token that can be used to access the API.

Client Registration - https://shop.merchantos.com/oauth/register.php
Authorization - https://shop.merchantos.com/oauth/authorize.php
Access Token Retrieval - https://shop.merchantos.com/oauth/access_token.php

Requesting Temporary Token

In a typical scenario, you have a user of your application who also has a MerchantOS account. They would like to grant access to your application to their data in MerchantOS. You have already registered a client with MerchantOS and have setup a page in your application that describes how your application will use data from MerchantOS to enhance the users experience. On this page you have a link to the Authorization end point (described above) with the following parameters: the of your application and the permissions that your application is requesting .

client_id: Your applications Client ID specified when you registered your client.
scope: The permissions that your application is requesting (see Access Token Permissions below for detail on what you can ask for).
request_type: Ask for code which will give you a temporary token that you can then use to get a permanent access token.

Retrieving Temporary Token

https://shop.merchantos.com/oauth/authorize.php?response_type=code&client_id={client_id}&scope={scope}

If the user authorizes your application for access they will be redirected to the Redirect URI that you specified when you registered your client. In the URI will be a parameter named code specifying the temporary token that can be used to retrieve the Access Token.

Redirect Response

{redirect_uri}?code={code}
    
e.g.: https://somedomain.com/oauth-receipt?code=3838838383

Once the temporary token is received the user interaction is complete. The temporary token is only valid for 1 minute, and the request to convert the temporary token to an Access Token should be made out of band to prevent visibility of client secret. The details of requesting an Access Token is described below.

Requesting Access Token

Once you have a temporary token it can be converted to an Access Token by passing your ClientID and the temporary token to the Access Token Retrieval endpoint. If the combination of ClientID and temporary token are recognized and the token is still valid then a JSON response will be returned with the Access Token and the permissions that granted to the Access Token.

client_id: Your applications Client ID specified when you registered your client.
client_secret: The secret you specified when you registered your client.
code: The code you received after completing the previous "Authorizing Your Client" step.
grant_type: Simply specify authorization_code to get the access token
redirect_uri: The redirect_uri as registered for the client

You must request access tokens request via POST so that your client_secret and code are sent encrypted (get parameters can be user-visible in some situations).

Retrieving Access Token

curl --data "client_id={client_id}&client_secret={client_secret}&code={code}&grant_type=authorization_code&redirect_uri={redirect_uri}" https://shop.merchantos.com/oauth/access_token.php

Access Token Permissions

An Access Token can have various levels of permission to access data. The level of permission is called its scope. When your application passes the user to MerchantOS to approve access you must specify the scope of access that your application needs. You are more likely to have the user grant access if you limit the scope you request to only the permissions that are necessary for your application to function.

Allowed Scopes

employee:all: Grants full read and write access to the account
employee:register: Create new Sales and read sales history.
employee:inventory: View, create, update, and archive items and inventory
employee:reports: View reports
employee:admin: View, create, update, and archive administrative records
employee:admin_shops: View, create, update, and archive shops
employee:admin_employees: View, create, update, and archive employees
employee:admin_purchases: View, create, update, and archive payment types, discounts, and taxes
employee:admin_void_sale: Void sales
employee:admin_inventory: View, create, update, and archive vendors and manufacturers
employee:workbench: View, create, update, and archive work orders
employee:change_password: Change passwords and PINs
employee:customers: View, create, update, and archive customers
employee:customers_credit_limit: View, create, update, and archive customer credit accounts

Using the Access Token

Once you have an Access Token it can be used to make requests to the API. It can be passed as a get parameter using the key oauth_token:

https://api.merchantos.com/API/Account/{accountID}/Item?oauth_token=[token_string]

Or in the Authorization header:

GET /API/Account/{accountID}/Item HTTP/1.1
Host: api.merchantos.com
User-Agent: Client Name
Accept: application/vnd.merchantos-v2+json
Authorization: OAuth [token_string]

MerchantOS

Help

Need a person? Request help and we'll get you on track.