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/ipn/tokenstoken. 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.

Attributes of the HTTP request

Attributes of the HTTP response

Examples

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

# HTTP POST
# https://ipnapp.dev.thinksurance.de/api/ipn/tokenstoken
# 'Content-Type': 'application/json'
# 'Accept': 'application/json'
{
  "hash": "some long string value",
  "secret": "some string value"
}

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

# 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.

...