Authorisation

Authorisation is necessary so that data can be accessed via the TWeb Public API. The process of authorisation involves a client requesting an Access Token by submitting its Client ID and Client Secret to the authorisation endpoint. Depending on parameters specified by the client, the Access Token may be via:

• the reponse body, or
• a HTTP cookie.

The Access Token will expire 30 minutes after it is issued, after which the client will need to authorise again.

Request

The authorisation endpoint depends on the server used by your company to login to TWeb:

The endpoint only accepts HTTP POST requests. The following POST parameters must be included with the request:

clientID
clientSecret
tokenStorageMedium

The Client ID and Client Secret will be given to you by Transponder Technologies. These are securely-generated random strings. The Client ID has the following validation rule specifications:

And the Client Secret has the following validation rule specifications:

The Token Storage Medium parameter accepts the values: body or cookie.

The following POST parameters may optionally be included with the request:

targetID

The Target ID can be used to link a request with its response, if necessary. When supplied it is always returned in the response. It has the following validation rule specifications:

Request Examples

A request that returns the Access Token as a cookie and stores it in cookiejar.txt:

curl -c cookiejar.txt -iskX POST -d "clientID=example123456789&clientSecret=example123456789&tokenStorageMedium=cookie&targetID=abc123" https://publicapi.tweb.com.au/v1/Authorise

A request that returns the Access Token in the response body:

curl -skX POST -d "clientID=example123456789&clientSecret=example123456789&tokenStorageMedium=body&targetID=abc123" https://publicapi.tweb.com.au/v1/Authorise

Response

The response from the authorisation endpoint has the following JSON format:

{
    "Data": {
        "Items": [
            {
                "AccessToken": "0123456789ABCDEF0123456789ABCDEF01234567"
            }
        ],
        "Meta": {
            "Endpoint": "/v1/Authorise",
            "TargetID": "abc123",
            "Title": "Public API: Authorisation"
        }
    },
    "Error": {
        "Code": 0,
        "Status": "OK"
    }
}

Note that the Data.Items JSON property will be empty, i.e. [], when the token storage medium is set to cookie.

The Access Token string conforms to the following rule specifications:

The Error JSON property is included in all responses from the TWeb Public API. The possible responses during authorisation are: