QuickStart

Getting an Access Token

Send a Username and Password to the Token endpoint to obtain an Access Token. The Access Token is then attached to calls to permissioned API endpoints, to identify the caller.

Back to Getting Started with the API

Access Tokens

This system uses the OAuth 2.0 Bearer Token system, a widely used and secure authentication and authorisation system. A good explanation of this system is provided by PostMan, an application that allows you to make HTTP calls manually...

Access Tokens contain encoded information identifying the User and their permission privileges. They have a limited lifespan, usually measured in minutes, so that the token can be used repeatedly in multiple API calls without having to authenticate each call.

Send Username and Password to Get an Access Token

The call to obtain a token requires the Username and Password for a User identity. The data should be sent in "application/x-www-form-urlencoded" format.

• username (mandatory)
• password (mandatory)

              
curl -X POST "https://prod.haggledigital.com/v01/token" ^
  -H "Content-Type: application/x-www-form-urlencoded" ^
  --data-urlencode "username=AshleyAuser" ^
  --data-urlencode "password=mySuperSecretPassword789"
              
            

              
curl -X POST "https://prod.haggledigital.com/v01/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "username=AshleyAuser" \
  --data-urlencode "password=mySuperSecretPassword789"
              
            

Response

The response will be an HTTP 200 OK message on success, or an error indicating a problem with the supplied data.

              
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}
              
            

Using the Access Token

The returned JSON data packet has the access_token element, where the value is the encoded JSON Web Token (JWT).

When making calls to permissioned API endpoints, the access_token string should be sent in the Header "Authorization" The value sent in the Authorization header should be "Bearer", followed by a space, and then the access_token string.

Decoding the Access Token

The Access Token is a standard JWT. You should be able to find a library for decoding JWTs in whatever language you work in. These tokens have three parts, delimited by a dot character:

header.payload.signature

The "payload" part is a UTF-8 string encoded in Base64URL format. If you decode this payload, it contains meta data about the token, like this:

              
{
  "sub": "AshleyAuser",
  "usr_pk": "AD4B9EB8-CA24-4642-9DAA-2895FF009001",
  "usr_role": 23,
  "exp": 1791540000
}     
              
            

The "exp" element holds a UNIX epoch date time, that gives the expiry of the token. It is best practice to store the token in a cache and request a new token when the current token expires.

The "sub" element holds the username. The "usr_pk" element holds a GUID string that is the internal system identifier for the user, often referred to as the User Key.

Always Use HTTPS

When making calls to permissioned API endpoints, always use the HTTPS protocol. If you use HTTP, this protocol uses clear text and the access_token string will be visible to possible bad actors monitoring network traffic.

Create Tradeable Items

With a User created and verified, and an Access Token obtained, all permissioned API endpoints can be called.

The next step is to create some Tradeable Items to represent the products, goods, commodities or currencies that you will trade in your Markets.

Continue to Create Tradeable Items.