Aston Club OAuth

To use the Aston Club services such as the Aston Club POS API and Payments API you will need a merchant or organization access_token to authenticate your user as a merchant. The following document outlines how to use Aston Auth to obtain a merchant access_token for use with POS API.

Aston Auth and it's associated APIs are intended to implement and conform to RFC6749. If something does not comply with OAuth2 and you think this is a mistake, please don't hesitate to contact support@astonclub.com.au.

Basic Overview

If you are familiar with OAuth 2 authorization code code based authentication then you can skip this section.

There is a lot of information on the Internet already (eg: this link), however this section will attempt to give a quick rundown on OAuth 2 authorization codes.

In order to use the service you will need to do the following:

Create a Connect Aston Club button that links to an Aston Auth URL as defined below.
Create a redirect page that exchanges a code for an access_token and refresh_token.
Create a system for updating expired access_tokens with a refresh_token.

The authorization process is as follows:

The user clicks the Connect Aston Club button in their browser.
The user's browser opens an Aston Club page where they will need to log in.
The user will be prompted to authorize the request to connect your app, and if they have access to more than one merchant they will be required to select one from a list.
The user's browser will be redirected back to your redirect page and provided with an code as a querystring parameter.
Your redirect page queries the Aston Auth API to exchange the code for an access_token.
Aston Club is now connected. You can store and use this access_token to access the connected Aston Club APIs.
When access_tokens expire you will need to get a new one using the refresh_token.

These steps are discussed in more detail below.

Environments

When this document references root relative urls such ass GET /token it is referencing to paths on the Aston Auth host.

For each environment these are:

Environment	Host
Sandbox	`https://auth-sandbox.astonclub.com.au`
Production	`https://auth.astonclub.com.au`

Authentication

/authorize/merchant

The first step in the process is to ask the user to authorize the a merchant. To do this you should have a Connect Aston Club button or link in your web app that links to https://{baseurl}/authorize/merchant?{queryparams} where baseurl is mentioned above, and queryparams are mentioned below.

The following query params are available.

Name	Type	Description
`client_id`	`string`	Required. The client id provided to you by Aston Club.
`response_type`	`string`	Required. `code` is the only supported value at this time
`redirect_uri`	`string`	The url you wish to send the user back to with the authorization code.
`scope`	`string`	the scope you wish to request, for Pos API this should be `posapi`.
`state`	`string`	A Random token to prevent XSS attacks.

Example URL: https://auth.astonclub.com.au/authorize/merchant?client_id=test_client&response_type=code&redirect_uri=https://youwebapp.com/oauth&scope=posapi&state=xyz

The customer will need to log in to the Aston Club authentication server with their Aston Club credentials, and will then be requested to approve the merchant authorization request.

If approved, Aston Club will redirect the customer's browser back to your site with a code that can be used to request a token. The state string is also returned and should be checked against the string sent to Aston Club.

Format: {yourredirecturl}?grant_type=authorization_code&code={yourauthorizationcode}&state={suppliedstate}

Example: https://youwebapp.com/oauth?grant_type=authorization_code&code=asn3733ne3ndfd&state=xyz

/authorize/organization

The first step in the process is to ask the user to authorize the a merchant. To do this you should have a Connect Aston Club button or link in your web app that links to https://{baseurl}/authorize/organization?{queryparams} where baseurl is mentioned above, and queryparams are mentioned below.

The following query params are available.

Name	Type	Description
`client_id`	`string`	Required. The client id provided to you by Aston Club.
`response_type`	`string`	Required. `code` is the only supported value at this time
`redirect_uri`	`string`	The url you wish to send the user back to with the authorization code.
`scope`	`string`	the scope you wish to request, valid scopes include `posapi`, `aston-api:transaction.read`, `aston-api:transaction.submit`. Multiple scopes can be requested by adding a space in between each scope.
`state`	`string`	A Random token to prevent XSS attacks.

Example URL: https://auth.astonclub.com.au/authorize/organization?client_id=test_client&response_type=code&redirect_uri=https://youwebapp.com/oauth&scope=aston-api:transaction.read%20aston-api:transaction.submit&state=xyz

The customer will need to log in to the Aston Club authentication server with their Aston Club credentials, and will then be requested to approve the merchant authorization request.

If approved, Aston Club will redirect the customer's browser back to your site with a code that can be used to request a token. The state string is also returned and should be checked against the string sent to Aston Club.

Format: {yourredirecturl}?grant_type=authorization_code&code={yourauthorizationcode}&state={suppliedstate}

Example: https://youwebapp.com/oauth?grant_type=authorization_code&code=asn3733ne3ndfd&state=xyz

Token Request

Once a code has been obtained, it can be exchanged by your server for an access_token using the /v1/token endpoint. You can then use this token to make requests in approved Aston Club APIs.

POST /v1/token

The /v1/token endpoint is used to get or create access_tokens and it can do this by providing either an authorization_code or an refresh_token.

Authorization Code

The following properties can be set in the body using content type header application/json or application/x-www-form-urlencoded

Name	Type	Description
`grant_type`	`string`	Required. `authorization_code` is the only value currently supported
`code`	`string`	Required. the `code` provided by the redirect from Aston Club.
`redirect_uri`	`string`	Required. the redirect URI used in the authorization request.
`client_id`	`string`	Required your client id.
`client_secret`	`string`	Required your client secret.

The response to this request will include the access_token you can use to request on the merchants behalf. expires_in is the number of seconds this token is valid for, if this is omitted the token will last indefinitely.

Example request:

POST https://auth.astonclub.com.au/v1/token
Content Type: application/json
{
  "grant_type": "authorization_code",
  "code": "abcd1234",
  "client_id": "test_client",
  "redirect_uri": "https://youwebapp.com/oauth",
  "client_secret": "asdajsjk@#$fjaksbfgjsabglbuwe@#@bfjesbj"
}

Example response:

{
  "access_token": "b3ced838247244107a252fe1f10aef34c78c726e",
  "token_type": "bearer",
  "expires_in": 31536000,
  "scope": "posapi",
  "resource_owner_type": "merchant",
  "refresh_token": "a324cc213e3c2ff25d1e62c6a81463de8f5ff7a2"
}

Refresh Token

The refresh token can similarly be used to generate additional tokens.

The following parameters are required.

Name	Type	Description
`grant_type`	`string`	Required. `refresh_token` is the only value currently supported
`refresh_token`	`string`	Required. the `refresh_token` provided in the previous step.
`client_id`	`string`	Required your client id.
`client_secret`	`string`	Required your client secret.

Example request:

POST https://auth.astonclub.com.au/v1/token
Content Type: application/json
{
  "grant_type": "refresh_token",
  "refresh_token": "a324cc213e3c2ff25d1e62c6a81463de8f5ff7a2",
  "client_id": "test_client",
  "client_secret": "asdajsjk@#$fjaksbfgjsabglbuwe@#@bfjesbj"
}

Example response:

{
  "access_token": "b3ced838247244107a252fe1f10aef34c78c726e",
  "token_type": "bearer",
  "expires_in": 31536000,
  "scope": "posapi",
  "resource_owner_type": "merchant"
}

Using the token

Once you have created a token scoped to posapi you can use that token to access POS API on behalf of a merchant.

To use the token, include it in a request's authorization header as a bearer token.

Authorization: Bearer b3ced838247244107a252fe1f10aef34c78c726e