Einleitung

TeamSIP Web stellt den Kunden eine REST-Schnittstelle bereit, diese wird als Kunden-Webservice bezeichnet.

Für die Nutzung ist Benutzername und Kennwort erforderlich, die Funktionen können via Web abgefragt werden.

Funktionsübersicht mit swagger ui

Aktuelle Version der Schnittstelle ist v2.
Version v1 wird demnächst eingestellt.
Bitte stellen Sie baldmöglichst auf Version v2 der Schnittstelle um.
Die Dokumentation zur Version kann oben rechts in der Seite umgestellt werden.

Beispiel URLs

https://www.teamsip.com/customerapi/swagger-ui.html

https://www.teamsip.com/customerapi/swagger-ui/index.html?urls.primaryName=customer-api-v2

Benutzer anlegen

Für die Nutzung des Kunden-Webservice ist ein entsprechender Nutzer mit Kennwort erforderlich.

Dieser Benutzer wird in der Benutzerverwaltung in TeamsipWeb angelegt. Notwendig ist das Recht Kundenadmin mit Webservice-Zugriff:

Nutzung und Anmeldung

Zunächst ist es erforderlich, am Server ein Accesstoken anzufordern. Mit Hilfe eines Accesstokens ist es möglich die verschiedenen Requests des Kunden-Webservice CustomerAPI zu nutzen.

Ein Accesstoken hat eine zeitlich begrenzte Gültigkeit. Diese Dauer wird in der Response mitgeliefert; "expires_in:" 300 bedeuted, dass das Accesstoken 300 Sekunden (5 Min) gültig ist. Danach ist es erforderlich ein neues Accesstoken anzufordern.

Im Request 1 fordert man mit seinem Username und Password das Accesstoken und Refreshtoken an. Die serverurl ist die Domain des Servers, also zum Beispiel www.teamsip.com .

OAuth-Request 1: Anmelden Oauth mit Username und Password:

Der erste Zugriff erfolgt mit Benutzer und Kennwort wie folgt, hiermit wird ein Access Token angefordert:

Beispiel mit Curl

curl --location --request POST 'https://{{serverurl}}/auth/realms/teamsip/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=cust-api' \
--data-urlencode 'username={{username}}' \
--data-urlencode 'password={{password}}'

BASH

Als Anwort erhält man diese Information:

Response (JSON-Format)

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIwVzhPazFFYlFydDVoclVYb1RQSFZxREIzWDhGSkJVY19QVEdvTmI5S2p3In0.eyJleHAiOjE2OTE1ODk0NDAsImlhdCI6MTY5MTU4OTE0MCwianRpIjoiMTVmYTExMWEtZTQ1OS00ODczLTlhNDktMTI0NzJlNTdkODIwIiwiaXNzIjoiaHR0cHM6Ly90cnVua2l4LWxiMS50ZWFtZm9uLmNvbS9hdXRoL3JlYWxtcy90ZWFtc2lwIiwic3ViIjoiYW1lX2N1c3RhZG1pbiIsInR5cCI6IkJlYXJlciIsImF6cCI6ImN1c3QtYXBpIiwic2Vzc2lvbl9zdGF0ZSI6IjkzZjMwOTcxLWI2YjUtNDNjMi1hOWVjLTU5OGRkZDZiMTdlYSIsInNjb3BlIjoiIiwic2lkIjoiOTNmMzA5NzEtYjZiNS00M2MyLWE5ZWMtNTk4ZGRkNmIxN2VhIiwidWlkIjoiZjpiYjk1YjA3Zi1hMDVkLTRiZjEtYjczNS02NzcxZmU4ZTY5NjM6YW1lX2N1c3RhZG1pbiJ9.kiN2xUHT5YC5Kk_d_VQB4WTnl9VRuV4SRtA83Yifs6UPk9_I9m-7eXUcBmtzFr01iCZId4PwI0LEZTfxN_bQES9LHufLfikAxKPn5f0GP4b1ZugKsh0HTxWW1xC3ZcmExGBCX34dCXktW93TAAViZ2QRr-p_wwvbRK6fIhdKC9ntmXgySPrvSMzD1Tirutlh8M8f1xyJQRM5plIetwFhMgDgQhTYzw61aQ9HZ8T8Y0nBVX9ExyhNJiZ4kIcCREcxi33ye6kR8Kz4jmyS78MzXjcuzLIjRdlsN2989DBqDPknVnedLjK85r-UWeWYU5THVvbPKM1lqkxD1nZtOUmGFA",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJmYTc1OTdlOS0xNWE4LTQ3MzgtOTRiOS0zMjViYWYxOGUyN2QifQ.eyJleHAiOjE2OTE1OTA5NDAsImlhdCI6MTY5MTU4OTE0MCwianRpIjoiNmMwYjUxOGItZjk0Ny00NGNlLWFlOGMtMzVlZTU4ZTU3YzdjIiwiaXNzIjoiaHR0cHM6Ly90cnVua2l4LWxiMS50ZWFtZm9uLmNvbS9hdXRoL3JlYWxtcy90ZWFtc2lwIiwiYXVkIjoiaHR0cHM6Ly90cnVua2l4LWxiMS50ZWFtZm9uLmNvbS9hdXRoL3JlYWxtcy90ZWFtc2lwIiwic3ViIjoiYW1lX2N1c3RhZG1pbiIsInR5cCI6IlJlZnJlc2giLCJhenAiOiJjdXN0LWFwaSIsInNlc3Npb25fc3RhdGUiOiI5M2YzMDk3MS1iNmI1LTQzYzItYTllYy01OThkZGQ2YjE3ZWEiLCJzY29wZSI6IiIsInNpZCI6IjkzZjMwOTcxLWI2YjUtNDNjMi1hOWVjLTU5OGRkZDZiMTdlYSJ9.PBEnlwmMGD7NUadNNq-LujxAgKBK8Yd6gE7TklsieJA",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "93f30971-b6b5-43c2-a9ec-598ddd6b17ea",
    "scope": ""
}

CODE

OAuth-Request 2: Anfordern neue Token mit Hilfe des Refreshtoken:

Ist ein Accesstoken abgelaufen (Man erhält einen HTTP-Error 401 zurück), fordert man mit Request 2 ein neues Tokenpaar aus Accesstoken und Refreshtoken an.

Dazu benötigt man nur das Refreshtoken aus dem jeweils letztem Oauth-Request.

Das Refreshtoken hat eine Gültigkeit von "refresh_expires_in": 1800 , also 30 min. Danach ist auch das Refreshtoken abgelaufen. In diesem Fall ist es wieder nötig sich mit Hilfe von OAuth-Request 1 ein neues Tokenpaar aus Accesstoken und Refreshtoken anzufordern.

Curl

curl --location --request POST 'https://{{serverurl}}/auth/realms/teamsip/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_id=cust-api' \
--data-urlencode 'refresh_token={{refresh_token des letzten Oauth-Requests}}'

BASH

Die Antwort lautet dann wie folgt:

Beispiel für die Response

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ6VGFaZDd0XzI3RU1jVmIweW5QcGVWOTNvMVpWNUtCc1h1Mmc0dWdYSmhjIn0.eyJleHAiOjE2OTE1OTM2OTQsImlhdCI6MTY5MTU5MzM5NCwianRpIjoiNTQzMTJhNjYtZTM1NS00ZjBlLTk2Y2ItYWVhOTFhMTM1ODUzIiwiaXNzIjoiaHR0cHM6Ly93d3cudGVhbXNpcC5jb20vYXV0aC9yZWFsbXMvdGVhbXNpcCIsInN1YiI6InNoYV93c190ZXN0IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiY3VzdC1hcGkiLCJzZXNzaW9uX3N0YXRlIjoiMjMyY2IxMGMtZjJhOC00NWU2LWIwYzUtYzQ4NDkyZTRmMjJiIiwic2NvcGUiOiIiLCJzaWQiOiIyMzJjYjEwYy1mMmE4LTQ1ZTYtYjBjNS1jNDg0OTJlNGYyMmIiLCJ1aWQiOiJmOmJiOTViMDdmLWEwNWQtNGJmMS1iNzM1LTY3NzFmZThlNjk2MzpzaGFfd3NfdGVzdCJ9.fz2YMlq0Vl8JqthFatAYRd6jaU88OMMvPblBfX4jzROVWB7etlAXk2dMQO_auZ2t2SyiaGR_8eDEECEhZSxLvUrDD8KZBuAkMMb3_1Fk4Bp6ruO-N-zwUYj-E6tUEna4MnQWJtkH4pDghIlXzXG3NzoxFci1HEPy3sM67JjMqslS4hih5G-IWCioixags-dO9aSNOCHYTWlFWAHXO2_ih0xRRBvAsCf1-hhGO7tYkFJUSimLSRDCQOv8UmvnZ7TF_KJDhQwfuGwiOmdEnj2gcbyziJ290X-expkr0b3aCC-dOY_Eo2hm7oisqT-K6bOpU4_OltCt680R896efttqlg",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI3N2MzN2FlZS03YjdkLTQyM2MtYjhkNC1iM2NjMGRmYWQ5NjMifQ.eyJleHAiOjE2OTE1OTUxOTQsImlhdCI6MTY5MTU5MzM5NCwianRpIjoiYzk2NWNiMDYtNjUxZC00NDgwLThkOGUtNGIzYWQwN2QzMjc4IiwiaXNzIjoiaHR0cHM6Ly93d3cudGVhbXNpcC5jb20vYXV0aC9yZWFsbXMvdGVhbXNpcCIsImF1ZCI6Imh0dHBzOi8vd3d3LnRlYW1zaXAuY29tL2F1dGgvcmVhbG1zL3RlYW1zaXAiLCJzdWIiOiJzaGFfd3NfdGVzdCIsInR5cCI6IlJlZnJlc2giLCJhenAiOiJjdXN0LWFwaSIsInNlc3Npb25fc3RhdGUiOiIyMzJjYjEwYy1mMmE4LTQ1ZTYtYjBjNS1jNDg0OTJlNGYyMmIiLCJzY29wZSI6IiIsInNpZCI6IjIzMmNiMTBjLWYyYTgtNDVlNi1iMGM1LWM0ODQ5MmU0ZjIyYiJ9.u3DXgKTyg-i-tzOgUl1nW3Y6un4tXpES3fPjQeQx6vI",
    "token_type": "Bearer",
    "not-before-policy": 1668586590,
    "session_state": "232cb10c-f2a8-45e6-b0c5-c48492e4f22b",
    "scope": ""
}

JS

Verwendung der Requests der CustomerAPI mit dem Accesstoken am Beispiel der Methode GET participants:

Nun kann man jede Methode der CustomerAPI aufrufen, indem man im RequestHeader die Authorization: Bearer {{access_token}} mitgibt

Curl

curl --location 'https://{{serverurl}}/customerapi/api/v1/participants' \
--header 'Authorization: Bearer {{access_token}}'

BASH

Allgemeine Informationen gibts es auch hier: https://auth0.com/docs/secure/tokens/access-tokens/use-access-tokens