V2 Authentication
- Timm Weitzel
Introduction
To authenticate against the Thinksurance Public API V2 (or just “the API“), it is imperative to obtain a access 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 access token has a limited validity period of 4 hours. 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/auth/v2/token For the successful execution of operations, two security-sensitive values, namely accessKey and secretKey, 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/auth/v2/token |
HTTP method | POST |
Attributes of the HTTP request
accessKey | string | required | A security-sensitive value provided by Thinksurance Support Team. Same value as “secret” |
|---|---|---|---|
secretKey | string | required | A security-sensitive value provided by Thinksurance Support Team. same value as “hash” |
Attributes of the HTTP response
Success response | |||
|---|---|---|---|
access_token | string | required | A security token required for future API usage. |
expires_in | integer | required | Number of seconds until access_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/auth/v2/token endpoint of the API. Below, instances of potential communication between the API and consumers are provided.
HTTP Request |
# HTTP POST
# https://rest.thinksurance.de/api/auth/v2/tokens
# 'Content-Type': 'application/json'
# 'Accept': 'application/json'
{
"accessKey": "some long string value",
"secretKey": "some string value"
} |
Successful HTTP Response |
# HTTP 200 status code
# 'Content-Type': 'application/json'
{
"access_token": "some long string value",
"expires_in": 14400,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"session_state": "6dfb33bc-c036-4841-b0df-3e9c71813145",
"scope": "general profile email"
} |
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.