TradeAware
  • Welcome to TradeAware User Guide
    • Getting Started
  • Using the TradeAware Web App
    • Upload and Analyzing Plots
    • Connect with your supply chain
    • Provide and Review Documents
    • Assess risk in your supply chain
    • Manage your transactions
    • Plot Upload and Analysis Trouble Shooting
    • How-to videos
  • Using the TradeAware API
    • API Access and Business Account Registration
    • Webhooks Guide
    • Authentication
      • Rotate client secret
      • Endpoints enabled for programmatic access
    • Upload and Analyzing Plots
    • Connect with your supply chain
    • Assess risk in your supply chain
    • Manage your transactions
    • API reference
      • Auth
      • Plots
        • Analyses of a specific Plot
        • Batch
      • Analyses
      • Attachments
      • Business invitations
      • Business connections
      • Transactions
        • Create a Transaction
        • Retrieve Transactions
          • Get a transaction by id
          • List all transactions
        • Modify an existing Transaction
          • Update a Transaction
          • Add a Transaction Component
          • Update a Transaction Component
          • Delete a Transaction Component
        • Delete a Transaction
        • Submit a Transaction
        • Retrieve DDS Data
      • Risk Assessments
        • Supplier Risk Assessments
          • Create a Supplier Risk Assessment
          • Update a Supplier Risk Assessment
          • Retrieve Supplier Risk Assessments
            • Get a supplier risk assessment by id
            • Get all supplier risk assessments
          • Retrieve the history
        • Plot Risk Assessments
          • Create a Plot Risk Assessment
          • Update a Plot Risk Assessment
          • Retrieve Plot Risk Assessments
            • Get a plot risk assessment by id
            • Get all plot risk assessments
          • Retrieve the history
      • Survey responses
      • Health
      • Version
      • Specification
  • Additional Resources
    • FAQs
    • Contact Support
    • Terms and Conditions
Powered by GitBook
On this page
  • Outline
  • Getting started
  • Interactions after authentication
  • Access token expiry and re-authentication
  • Next steps
  1. Using the TradeAware API

Authentication

Programmatic access

PreviousWebhooks GuideNextRotate client secret

Last updated 9 months ago

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 .

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 and navigate to the . 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 to see what endpoints are available.

list of such endpoints here
TradeAware Web Application
Developer Tools
API reference documentation