Token Authentication

Introduction

EML has a suite of REST APIs available under its Web Services 3.0 umbrella. Each of these APIs share a common security and authentication model based on OAuth 2.0.

This document describes that model, and the steps necessary to obtain an access token and begin consuming our APIs.

API Endpoints

• Production
  • https://ws.emerchants.com.au/3.0/token
• Beta
  • https://beta.emerchants.com.au/3.0/token

OAuth 2.0

Our WS3 APIs leverage OAuth 2.0 for authentication and authorization. OAuth 2 Simplified may be good to read if you want to learn more about it, though that's not necessary to use the APIs.

There are OAuth 2.0 client libraries available for many popular languages, which may simplify the integration process. If no library is available for your language, or you prefer to have more control, it is quite easy to implement the workflow yourself using simple HTTP and JSON.

The following sections document EML's OAuth 2.0 workflow in detail.

Pre-requisite Configuration

EML will provide you with a client_id and client_secret to use with our Token API. You can think of them as a randomly generated username and password.

Example request for basic access authentication:

{
    "client_id" : "7c86534ad78805d616778e9a84a5365a",
    "client_secret" : "4690cd9e5e2f07ccd92057bf0f487156"
}

You will need these credentials prior to obtaining an access token. Also note that these credentials will change between production and each of our test environments.

Obtaining an access token

You will need to provide a valid access token when accessing any secured resource from our WS3 APIs. Access tokens are obtained by making a POST request to the /token resource.

This request must be made up of the following components:

1. An Authorization header containing a valid client_id and client_secret.
   • This header uses standard HTTP Basic Authentication.
   • Specifically, the header is formulated as: Authorization: Basic <credentials>. The credentials are combined in text as client_id:client_secret, and then encoded using the RFC2045-MIME variant of Base64.
2. A Content-Type header set to application/x-www-form-urlencoded
3. A body containing grant_type=client_credentials

This is demonstrated in the following example:

POST /3.0/token HTTP/1.1
Host: ws.emerchants.com.au
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

If your client credentials are correct, the API will return a 200 OK response containing an access token, as demonstrated by the following example:

{
    "access_token": "AcMCRbJRSmyLFbIRQxMvFB5xZ6cBjghjN3/YEoxGKWkKNZkqnfE=",
    "token_type": "bearer",
    "expires_in": 43199
}

The access_token in this response can then be used to access other WS3 APIs.

Token Expiry

You will also need to be prepared to get a new access token before this one expires. The expires_in property on the response measures the expiry time in seconds.

See Token lifecycle for hints on managing token expiry.

Using the access token

Now that you have obtained an access token, you can use it to access other WS3 APIs. To do so, simply include it as an HTTP Bearer Token in requests to those APIs. This is accomplished by setting the Authorization header in your requests in the format of Authorization: Bearer <access_token>.

This is demonstrated in the following example:

GET /3.0/accounts HTTP/1.1
Host: ws.emerchants.com.au
Authorization: Bearer AcMCRbJRSmyLFbIRQxMvFB5xZ6cBjghjN3/YEoxGKWkKNZkqnfE=

Token lifecycle

You should continue to re-use the same access token until shortly before it expires. At this time, you should repeat the above steps to get a new access token.

Our tokens are currently issued with 12 hour lifespans. However, you should build your application logic around the expires_in property, as we may re-configure this lifespan without notice.

You application should implement some strategy to maintain a valid access token. We recommend the strategy as follows:

• If, when attempting to use your current access token, there is less than 2 minutes remaining before it expires, trigger an asynchronous process to get a new access token. Continue using the old access token until the process completes and the new access token becomes available.
• If you receive a 401 UNAUTHORIZED response at any point, request and wait for a new access token, then try your original request again.

Concurrent Tokens

If required, you can safely request multiple access tokens across your distributed application. Creating new tokens does not invalidate previous ones, and all access tokens will remain valid until they expire.

That said, be aware that the /token endpoint is not intended for low latency or high throughput. Do not design your application to use a new access token for every request.

Other Security Measures

I.P. Address Whitelisting

EML maintains a whitelist of I.P. addresses which are permitted to access its APIs. Before you can access either test or production endpoints, you will need to contact EML and provide us with the public I.P. addresses from which you wish to access our APIs. You may provide one or more IP addresses (or subnets) to be whitelisted in each environment. Be aware that we will not whitelist subnets larger than /29 (IPv4).

Please note that our policy dictates that a single IP address cannot be simultaneously whitelisted in both the test and production environments.

Be advised that there is some lead time involved with adding or modifying the whitelist.

Important Usage Note

All JSON sent to and from the API must be sent with the Content-Type HTTP header set to application/vnd.eml+json. This is to prevent any confusion caused by intermediate proxies and gateways which may send application/json under some conditions.