Authentication

Authentication is required to use the API endpoints. All calls without authentication will return the status code 401 Unauthorized.

The authentication is done with JWT (JSON Web Token, see Wikipedia). There are two ways to obtain a token:

• To obtain a token with your user name (your mail address) and password, use the endpoint [POST] /authenticate.
• To obtain a token with an API key you have created in your MapTrip Manager account, use the endpoint [POST] /authenticate/apikey.

This token is used for authorization in all further requests.

In both cases, you can specify the duration of the token's validity when you call the endpoint. The duration can be up to 30 days. After expiration of the validity a new token must be requested.

In the following we assume that you have a valid user name and password.

Obtaining a JWT token

You can use the endpoint [POST] /authenticate to obtain a token to use the API. You have to specify our user name and password as parameters. Optionally, you can also specify the duration of the validity in seconds.

Request to [POST] /authenticate

Here is an example request for a token which is valid for a week. The duration is specified in seconds, therefore the value is 7 * 24 * 60 * 60 = 604800.

Example curl command:

curl -X POST "https://api.maptrip.de/v1/authenticate" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"duration\": 604800, \"password\": \"myPassword\", \"user\": \"user@example.org\"}"

Response

The response for a successful request contains the token itself an for convenience the Authorization header which can be used for API calls, i.e. Bearer <token>.

1
2
3
4

{
  "token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJnb2xkYmFjaEBpbmZvd2FyZS5kZSIsImF1dGgiOiJST0xFX1JPT1QiLCJpZCI6MjYzMDQsImV4cCI6MTYzMTk3NjQzM30.nbU24qeOu35xE2rhyCDv3woTpGAUTdGVXkZPod0ixLbOObLVwIxYMiFsZ2NAjmGGfuotYqUy4_0nj9Nq5EYisw",
  "authorization": "Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJnb2xkYmFjaEBpbmZvd2FyZS5kZSIsImF1dGgiOiJST0xFX1JPT1QiLCJpZCI6MjYzMDQsImV4cCI6MTYzMTk3NjQzM30.nbU24qeOu35xE2rhyCDv3woTpGAUTdGVXkZPod0ixLbOObLVwIxYMiFsZ2NAjmGGfuotYqUy4_0nj9Nq5EYisw"
}

Obtaining a JWT token with an API key

If you have created an API key in your MapTrip Manager account, you can use the endpoint [POST] /authenticate/apikey to obtain a token with your API key. Optionally, you can also specify the duration of the validity in seconds.

Request to [POST] /authenticate/apikey

Here is an example request for a token which is valid for 30 days. The duration is specified in seconds, therefore the value is 30 * 24 * 60 * 60 = 2592000.

Example curl command:

curl -X POST "https://api.maptrip.de/v1/authenticate/apikey" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"apikey\": \"37348789-4eb4-4d89-bbad-34d451185f92\", \"duration\": 2592000}"

The response format for this endpoint is the same as for [POST] /authenticate.

Using a JWT Token

In the web interface

For a simplified introduction to the MapTrip Server API the API web page offers the possibility to request a token directly. Click on the Button Authorize in the upper right corner and enter received token (without the word Bearer which is added automatically). After clicking Authorize, the token is automatically sent with all subsequent requests.

Use per curl

curl commands allow the use of HTTP headers by specifying the parameter -H. Multiple headers are allowed by specifying the parameter more than once. The token has to be specified with the parameter -H "Authorization: Bearer <token>":

curl -X GET "https://api.maptrip.de/v1/geocoder?provider=TomTom&address=Berlin&country=DEU&limit=1" -H "accept: application/json" -H "Authorization: Bearer eyJhbGciiJ9.eyJ_-wRHLP5cwBlXs7....."

Use from within an application

As in the curl command, the token must be sent with every HTTP call. The passing of the parameters and the HTTP header Authorization "Bearer " are of course dependent on the programming language used.