Introduction

To authenticate against the Thinksurance Public API V1 (or just “the API“), it is imperative to obtain a security token and employ it for accessing other available endpoints. Subsequent API calls must consistently incorporate this acquired token, as described in each corresponding endpoint documentation. The security token has a limited validity period of 15 minutes. Consequently, upon expiration of the token, it becomes imperative to initiate the retrieval of a new token from the API.

Endpoint

To obtain a security token, it is requisite to send a POST HTTP request to the API at the designated path /api/token. For the successful execution of operations, two security-sensitive values, namely hash and secret, must be provided by Thinksurance Support Team. Following the provision of these values as a JSON payload in the HTTP request, the API will respond by returning a security token within a JSON payload in the HTTP response.

Action name	get token
HTTP path	/api/token
HTTP method	POST

Attributes of the HTTP request

hash	string	required	A security-sensitive value provided by Thinksurance Support Team.
secret	string	required	A security-sensitive value provided by Thinksurance Support Team.

Attributes of the HTTP response

Success response
token	string	required	A security token required for future API usage.
expired	string	required	Date and time when the security token expires. MySQL format for datetime: {{ YYYY-MM-DD hh:mm:ss }}
Failed response
error	string	required	It contains a reason for the failed request.

Examples

As previously stated, to procure a security token, it is imperative to dispatch a POST HTTP request to the /api/token endpoint of the API. Below, instances of potential communication between the API and consumers are provided.

HTTP Request

# HTTP POST
# /api/token
# 'Content-Type': 'application/json'
# 'Accept': 'application/json'
{
  "hash": "some long string value",
  "secret": "some string value"
}

Successful HTTP Response

# HTTP 200 status code
# 'Content-Type': 'application/json'
{
  "token": "some long string value",
  "expired": "2024-01-26 14:54:46"
}

Failed HTTP Response

# HTTP 200 status code
# 'Content-Type': 'application/json'
{
  "error": "API User is not existing or deactivated."
}

Sequence diagram

Throughout the lifespan of a security token, consumers are entitled to submit requests to various endpoints within the API. Upon receiving the first response indicating an invalid request, consumers of the API should initiate the retrieval of a new security token.

Authentication