Sitzungsfunktionen - customX REST-Schnittstelle

⚙️ Verfügbar ab: Release 6

🧩 Dieser Artikel enthält Funktionalitäten einer oder mehr Zusatzoptionen

Details zu den vorangegangenen Versionen der API sind im Abschnitt „Frühere API-Versionen“ am Ende dieses Artikels dokumentiert.

Login und gleichzeitigem Starten einer neuen Sitzung

Mit dieser Methode authentifiziert sich ein Benutzer an der Anwendung und startet gleichzeitig eine neue Sitzung. Nach erfolgreicher Anmeldung werden eine eindeutige Sitzungs-ID sowie ein Access-Token zurückgegeben. Das Access-Token ist für die Authentifizierung bei allen weiteren API-Aufrufen erforderlich.

Methode

POST Api/v3/Login HTTP/1.1
X-Api-Key: [apiKey]
Content-Type: application/json
Host: [Host]

{
  "username": "[userName]",
  "password": "[userPassword]",
  "culture": "[culture]"
}

Header

Für den Aufruf dieser Methode wird ein gültiger API-Key benötigt.

 

Request-Body

Für diese Methode müssen die Attribute username, password und culture übergeben werden.

Attribut	Beschreibung	Typ	Erforderlich
username	Benutzername, der durch einen customX-Administrator bereitgestellt wird.	String	Ja
password	Password, das durch einen customX-Administrator bereitgestellt wird.	String	Ja
culture	Legt die Culture fest, die für die Darstellung im Webbrowser verwendet wird. Die Culture beeinflusst kulturspezifische Formatierungen, wie z. B. Datums- und Kalenderformate, Währungsdarstellungen sowie die Formatierung reeller Zahlen. Die Angabe erfolgt im Format <language code>[-<country/region code>], z. B. de-DE, en-US, de-CH.	String	Ja

Antwort

Bei erfolgreicher Ausführung werden eine neue Sitzungs-ID sowie ein Access-Token zurückgegeben.

Das Access-Token muss bei allen nachfolgenden API-Aufrufen zusätzlich zum API-Key im HTTP-Header Authorization übermittelt werden.

Beispielantwort:

{
  "sessionId": "6b0c7940e1114a878d6ca0f2741c7abf",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY3AiOiJBY2Nlc3MiLCJpc3MiOiJjdXN0b21YIiwic3ViIjoiZmRkOGRlMmE1OTgyNGNmMjk2M2RlYWE1ZTIyNTA2MzAiLCJuYmYiOjE3ODg3NjU0NzgsImV4cCI6MTc4ODgwODY3OCwiaWF0IjoxNzg4NzY1NDc4fQ.N0dCo0uNAPb3RyWYYJ32SUdKI_JurM1jhhHKlZxoo9E"
}

 

Fehlerbehandlung

Tritt ein Fehler auf, enthält die Antwort entsprechende Informationen zum Fehlerzustand. Struktur und Inhalt der Fehlermeldung können je nach Fehlerursache variieren.

 

 

Logout mit Beenden der Session

Mit dieser Methode wird die aktuelle Benutzersitzung beendet. Nach erfolgreicher Ausführung verliert das verwendete Access-Token seine Gültigkeit und kann nicht mehr für weitere API-Aufrufe verwendet werden.

Methode

POST Api/v3/Logout HTTP/1.1
X-Api-Key: [apiKey]
Authorization: Bearer [accessToken]
Content-Type: application/json
Host: [Host]

{}

Header

Für den Aufruf dieser Methode werden ein gültiger API-Key sowie ein Access-Token benötigt.

Request-Body

Für diese Methode sind keine Eingabeparameter erforderlich.

Antwort

Bei erfolgreicher Ausführung wird der Wert true zurückgegeben.

Beispielantwort:

true

 

Fehlerbehandlung

Tritt ein Fehler auf, enthält die Antwort entsprechende Informationen zum Fehlerzustand. Struktur und Inhalt der Fehlermeldung können je nach Fehlerursache variieren.

 

Sitzung an Webbrowser übergeben

⚙️ Verfügbar ab: Release 8.49

Mit dieser Methode kann die aktuelle Anwendungssitzung an einen Webbrowser übergeben werden. Hierzu wird ein Transfer-Token erzeugt, das anschließend für die Authentifizierung bzw. Übernahme der bestehenden Sitzung im Browser verwendet werden kann.

Prozessbeschreibung

1. Der externe Service sendet eine HTTP-Anfrage an den Endpunkt HandOverSession.

2. Der API-Controller erzeugt einen zeitlich begrenzt gültigen Transfer-Token.

3. Der Transfer-Token wird als Antwort an den aufrufenden Service zurückgegeben.

4. Der Service erstellt die Ziel-URL für den Webbrowser. Dabei gilt:
   1. Die Einstiegsseite ist Start.html.
   2. Der URL-Parameter transfertoken enthält den zuvor erzeugten Transfer-Token.

   https://[URL]/Start.html?transfertoken=XXXX.XXXX.XXXX

    

5. Der Webbrowser öffnet die erzeugte URL.

6. Der Webbrowser ruft den entsprechenden Endpunkt auf und überprüft den Tansfer-Token.

7. Nach erfolgreicher Validierung wird die Eigentümerschaft der Sitzung auf den Webbrowser übertragen.

8. Der Webbrowser erhält die erforderlichen Informationen als Antwort zurück.

Methode

GET Api/v3/HandOverSession HTTP/1.1
X-Api-Key: [apiKey]
Authorization: Bearer [accessToken]
Content-Type: application/json
Host: [Host]

{}

Header

Für den Aufruf dieser Methode werden ein gültiger API-Key sowie ein Access-Token benötigt.

 

Request-Body

Für diese Methode sind keine Eingabeparameter erforderlich.

Antwort

Bei erfolgreicher Ausführung wird ein Transfer-Token zurückgegeben, das für die Übernahme der Sitzung im Webbrowser verwendet werden kann.

Beispielantwort:

{
   "transferToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJjdXN0b21YIiwic2Vzc2lvbmlkIjoiNmIwYzc5NDBlMTExNGE4NzhkNmNhMGYyNzQxYzdhYmYiLCJuYmYiOjE3ODg3NjU0ODcsImV4cCI6MTc4ODc2NTc4NywiaWF0IjoxNzg4NzY1NDg3fQ.o936mSN4-_JwmjsrKZv-ojRfa-EnNxJbAOYDCuNN7E0"
} 

 

Fehlerbehandlung

Tritt ein Fehler auf, enthält die Antwort entsprechende Informationen zum Fehlerzustand. Struktur und Inhalt der Fehlermeldung können je nach Fehlerursache variieren.

 

---

Frühere API-Versionen

Login und gleichzeitigem Starten einer neuen Sitzung

Example POST URL:
http://localhost/CustomXApp/Api/Login

Example POST body:
{
"username": "Max",
"password": "geheim",
"culture": "de-DE"
}

Example response:
c009f9dc

Error response:
null

Erforderliche Parameter

Antwortdetails

Die Antwort enthält entweder die ID der neu angelegten Sitzung oder null im Falle eines Fehlschlags.

---

Logout mit Beenden der Session

Example POST URL:
http://localhost/CustomXApp/Api/Logout

Example POST body:
{
"sessionid": "c009f9dc"
}

Example response:
true

Erforderliche Parameter

Antwortdetails

Die Antwort lautet true für ein einfolgreiches Abmelden und false für einen Fehlschlag.