V1 Authentication
- Timm Weitzel
- Marko Milojevic
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. |
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
# https://app.dev.thinksurance.de/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.
Â
Â