Overview / Getting started

API Endpoints

There are multiple endpoints for different environments:

Production:
https://middleware.services.tasko.de/v1/

Stage / Test:
https://stage-middleware.services.tasko.de/v1/

IP Whitelisting

Access to the API Endpoints is restricted by a IP whitelist. Please contact entwicklung@tasko.de to get whitelisted.

General Information

The API is implemented as a RESTful API based on the API Platform framework.

Content Types

By default all request and responses bodies are JSON objects. Therefor the Accept and Content-Type HTTP headers should be set to application/json.

Status Codes

Code	Comment
200	A succesfull request with a reponse body
201	A successfull request that created a new entity usally returning the entity
204	A successfull request without a response body
500	Server side error
401	Missing JWT authorization header
403	Not authorized to perform the requested action
422	The client send invalid data / Validation failed

Authentication

All request to the Middleware API must be authenticated. Please contact entwicklung@tasko.de to obtain your personal user credentials. You will receive different credentials for the Production and Stage environment.

Authentication is handled via JWT (=JSON Web Token) - for more information see https://jwt.io/. The JWT must be sent in every request to the API in a Authorization header.

Example:

curl --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" https://stage-middleware.services.tasko.de/v1/some_api_endpoint

Obtain a JWT

Before you can access any API Endpoints you will have to authenticate and obtain a JWT. You should do this once and then store the JWT safely to reuse it in all upcomming requests. Please be aware that JWTs have a lifetime and must be refreshed after a given time. See Refresh a JWT.

HTTP Request: POST /auth/get_token
Request Body:

Key	Type	Comment
username	string
password	string

Example:

{
    "username": "yourname",
    "password": "youpw"
}

Success Status Code: 200
Response Body:

Key	Type	Comment
token	string	JWT Token
refreshToken	string	Token to refresh the JWT

Example:

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2MzQ3MjQ5ODEsImV4cCI6MTYzNDcyODU4MSwic3ViIjoiNiIsInJvbGVzIjpbIldFQkhPT0tfSU5WT0tFIl0sInVzZXJuYW1lIjoic2VydmljZSIsInR5cGUiOiJzZXJ2aWNlIn0.dIC3TQbx3TaBDkfcneK5uSZhRV6LWU37T2SlIjz2jCbte6xMuCTxRX22qGAAhDZHM-uRMNPAYbogZCUUtVczQY__eh56Z4Z3yV0p9LHUvDsiToqrl2Q10Y3uc6Ef-gt2pmZsyiXv0TGxL9pZiQ4Wr4Ntx7L6C_lAkbqKbF2OsvrG_3vPouekzOV4Q4cI-v-_TeuEqzXLrQzm5G2a9y8_b17q6B7b4P1GGOnn32EH-xFYRlZvXJK9EHuK8CfavZUalM3YbmZg7YOrUwpB9mw708VeOfQUmHZ8GsFtdgK5WwqFsdPiw02mxFgETKz5qaLZwzAQxMHZPzbVNtxyrA2ZYwACc6gLeDeG7p0Iq0fueaotXWoeh-u3C7yomTjGJK9uadBHqnuvqfkun8k5LYXShl3Ij74YM7fH5zazDdY1BMat_oAAwXhxjQCAFinZZoEVLMC44xpN74uwNEyheYnuscc5-U_ctr6zr1GTichUc4Tj5nvP4y7-DHpxBM9FqWIMIk-wh-fWX1aRZ1VHmSuXeE5ETKt0bUVC50Mboignf4MOfmiPJDiV1c62zS7mQhPP07AIiiIqA7iJAwm-mWTq-BBnGWE9sZSZ6GmMUZFSZCFyhz0JXOWMUE6WlQ9K0Z87dQGV_FKrm1XpN_ft3QSykFhFqKghadlMVazMErEvF_Q",
  "refreshToken": "272df112c4f99c16257b22cdbeb95f43099b6928f29f058793eae6c63ff152d6af521fa26459aa86566371b3dda7e539386dd00255fb158635541747dee41373"
}

Refresh a JWT

As JWTs have a lifetime, currently 1 hour, after which they expire and have to be refreshed. The refresh token has a lifetime of 24 hours. This means after 24 hours the client must reauthenticate with it's user credentials.

HTTP Request: POST /auth/refresh_token
Request Body:

Key	Type	Comment
refreshToken	string

Example:

{
  "refreshToken": "272df112c4f99c16257b22cdbeb95f43099b6928f29f058793eae6c63ff152d6af521fa26459aa86566371b3dda7e539386dd00255fb158635541747dee41373"
}

Success Status Code: 200
Response Body:

Key	Type	Comment
token	string	JWT Token
refreshToken	string	Token to refresh the JWT

Example:

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2MzQ3MjQ5ODEsImV4cCI6MTYzNDcyODU4MSwic3ViIjoiNiIsInJvbGVzIjpbIldFQkhPT0tfSU5WT0tFIl0sInVzZXJuYW1lIjoic2VydmljZSIsInR5cGUiOiJzZXJ2aWNlIn0.dIC3TQbx3TaBDkfcneK5uSZhRV6LWU37T2SlIjz2jCbte6xMuCTxRX22qGAAhDZHM-uRMNPAYbogZCUUtVczQY__eh56Z4Z3yV0p9LHUvDsiToqrl2Q10Y3uc6Ef-gt2pmZsyiXv0TGxL9pZiQ4Wr4Ntx7L6C_lAkbqKbF2OsvrG_3vPouekzOV4Q4cI-v-_TeuEqzXLrQzm5G2a9y8_b17q6B7b4P1GGOnn32EH-xFYRlZvXJK9EHuK8CfavZUalM3YbmZg7YOrUwpB9mw708VeOfQUmHZ8GsFtdgK5WwqFsdPiw02mxFgETKz5qaLZwzAQxMHZPzbVNtxyrA2ZYwACc6gLeDeG7p0Iq0fueaotXWoeh-u3C7yomTjGJK9uadBHqnuvqfkun8k5LYXShl3Ij74YM7fH5zazDdY1BMat_oAAwXhxjQCAFinZZoEVLMC44xpN74uwNEyheYnuscc5-U_ctr6zr1GTichUc4Tj5nvP4y7-DHpxBM9FqWIMIk-wh-fWX1aRZ1VHmSuXeE5ETKt0bUVC50Mboignf4MOfmiPJDiV1c62zS7mQhPP07AIiiIqA7iJAwm-mWTq-BBnGWE9sZSZ6GmMUZFSZCFyhz0JXOWMUE6WlQ9K0Z87dQGV_FKrm1XpN_ft3QSykFhFqKghadlMVazMErEvF_Q",
  "refreshToken": "272df112c4f99c16257b22cdbeb95f43099b6928f29f058793eae6c63ff152d6af521fa26459aa86566371b3dda7e539386dd00255fb158635541747dee41373"
}