User Guide: Authentication

Programmatic access

Outline

You can use the TradeAware API programmatically to do actions on behalf of your business.

The general steps involve

• Authentication to receive an access token.

• Interactions on behalf of a business using the access token.

• Re-authentication once the access token expires.

Important: Currently only a limited number of endpoints are enabled for access via OAuth2.0 machine-to-machine client. Please find the list of such endpoints here.

We will enable further endpoints for programmatic access as our customer use-cases develop.

Getting started

Creating an OAuth2.0 machine-to-machine client and client credentials

The TradeAware API uses OAuth2.0 machine-to-machine client authentication (Client Credentials Flow) to authenticate businesses that interact with the TradeAware API programmatically.

To get started interacting with programmatic access to the TradeAware API, login to the TradeAware Web Application and navigate to the Developer Tools. Alternatively to using the URL directly, you may do the following: After login, click the profile icon in the bottom left corner, then choose "Manage Account". Then, click "Developer Tools".

If you have not created an OAuth2.0 machine-to-machine client before, the app will ask you to create one. Confirm by clicking "Yes, create client".

The Developer Tools page will then display the client credentials to authenticate:

• Client ID

• Client secret

Retrieve an access token

With these client credentials, you can programmatically create an access token for temporary access to the API. For enhanced security, the access token will expire after one day. After that, you can use the client credentials again to create a new access token.

You request a token with the following HTTP request (make sure to insert your own client ID and client secret)

curl --request POST \
  --url https://api.tradeaware.live-eo.com/auth/machine-to-machine-clients/token \
  --header 'Content-Type: application/json' \
  --data '{"client_id":"<YOUR_CLIENT_ID>","client_secret":"<YOUR_CLIENT_SECRET>","grant_type":"client_credentials"}'

On success, this will respond with an access token as follows:

{
  "access_token": "<JWT_VALUE_HERE>",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "read:example"
}

Interactions after authentication

Next, use the access_token from the previous section's response body to authenticate and interact with the TradeAware API. For example,

curl https://api.tradeaware.live-eo.com/plots \
  --header 'Authorization: Bearer <JWT_VALUE_OF_ACCESS_TOKEN_HERE'

Example response

You should receive an HTTP status code of 200 and, if you have not yet created any plots using the TradeAware Web Application, the response body will be an empty array.

[]

Access token expiry and re-authentication

After the access token has expired, the TradeAware API will respond with an HTTP status code of 401 Unauthenticated. Once that happens, you will need to re-authenticate using the Client Credentials Flow described in the section "Retrieve an access token" above.

We kindly ask you to reuse the Access Token instead of re-authenticating on every request, if possible.

Next steps

From here, you can interact with the TradeAware API on behalf of your business by including the access token in the Authorization header of your HTTP requests as explained above.

Check out the API reference documentation to see what endpoints are available.