API Authentication

Diese Seite beschreibt, wie man sich beim Calenso API einen Access-Token holen kann und mit diesem schlussendlich mit dem API kommuniziert.

📖 Voraussetzungen

  • Du hast eine Enterprise Calenso-Lizenz
  • Calenso hat dir einen entsprechenden Client (Client-ID, Client-Secret) zur Verfügung gestellt
  • Du hast Zugriff auf die API-Docs unter https://apidocs.calenso.com/

🔒 Access-Token

Um mit dem Calenso API kommunizieren zu können, muss zuerst ein Access-Token angefordert werden:

cURL

curl --request POST \
--url 'https://calenso.eu.auth0.com/oauth/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data grant_type=client_credentials \
--data client_id=YOUR_CLIENT_ID \
--data client_secret=YOUR_CLIENT_SECRET \
--data audience=https://my.calenso.com/api/v1

C#

var client = new RestClient("https://calenso.eu.auth0.com/oauth/token");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/x-www-form-urlencoded");
request.AddParameter("application/x-www-form-urlencoded", "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&audience=https://my.calenso.com/api/v1", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Go

package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://calenso.eu.auth0.com/oauth/token"
payload := strings.NewReader("grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&audience=https://my.calenso.com/api/v1")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("content-type", "application/x-www-form-urlencoded")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}

Java

HttpResponse<String> response = Unirest.post("https://calenso.eu.auth0.com/oauth/token")
.header("content-type", "application/x-www-form-urlencoded")
.body("grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&audience=https://my.calenso.com/api/v1")
.asString();

NodeJS

var axios = require("axios").default;
var options = {
method: 'POST',
url: 'https://calenso.eu.auth0.com/oauth/token',
headers: {'content-type': 'application/x-www-form-urlencoded'},
data: new URLSearchParams({
grant_type: 'client_credentials',
client_id: 'YOUR_CLIENT_ID',
client_secret: 'YOUR_CLIENT_SECRET',
audience: 'https://my.calenso.com/api/v1'
})
};
axios.request(options).then(function (response) {
console.log(response.data);
}).catch(function (error) {
console.error(error);
});

PHP

$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://calenso.eu.auth0.com/oauth/token",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&audience=https://my.calenso.com/api/v1",
CURLOPT_HTTPHEADER => [
"content-type: application/x-www-form-urlencoded"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}

✉️ Response

Wenn alles gut geht, bekommst du eine HTTP 200 Antwort vom Server mit einem Payload, welcher den access_token, token_type und expires_in enthält:
{
"access_token":"eyJz93a...k4laUWw",
"token_type":"Bearer",
"expires_in":86400
}

⌛ Gültigkeit des Access-Tokens

Der Access-Token ist standardmässig 86400 Sekunden oder 24 Stunden gültig. Es muss zwingend geprüft werden, ob der Token gültig ist, bevor ein neuer Token angefordert wird. Der Grund ist, dass Auth0 ein maximales Kontingent an M2M Tokens pro Monat zur Verfügung stellt. Missachtet ein Entwickler diese Best-Practice, dann wird sein Client gesperrt (wenn mehr als 31 Tokens im Monat verbraucht werden). Zusätzlich verbrauchte Tokens werden in Rechnung gestellt.

🖥️ API-Call

Um die API von der M2M-Anwendung aus aufzurufen, muss die Anwendung das abgerufene Access Token als Bearer Token im Authorization Header Ihrer HTTP-Anfrage übergeben.

cURL Beispiel

curl --request GET \
--url https://my.calenso.com/api/v1/workers \
--header 'authorization: Bearer ACCESS_TOKEN' \
--header 'content-type: application/json'
API Endpoints:
  • PROD: https://my.calenso.com/api/v1/
  • Entwicklungssystem für Kunden: https://api.calenso.io/api/v1/