| Note |
|---|
Sie benötigen zum Set-up die Berechtigungsrollen: Allgemein: Zugang zur Verwaltungsübersicht API Dokumentation: Alle Berechtigungsrollen unter “Administration” API-Zugang: Alle Berechtigungsrollen unter “Administration”
Es hat sich bewährt, für diese Art der Berechtigungen eine eigene Berechtigungsgruppe (z. B. Developer) anzulegen und diese ausgewählten Benutzer:innen zu Verfügung zu stellen. |
1. Einrichtung der API-Zugänge / AutorisierungsdatenRufen Sie die Verwaltung für API-Zugänge auf und erstellen Sie die benötigten API-Zugänge. Eine detaillierte Anleitung finden Sie hier: https://peiq.atlassian.net/wiki/spaces/PPSDPUPKB/pages/249168027/API+Zug+nge+verwalten#API249168027#API-Zugang-erstellen | Note |
|---|
Bitte beachten Sie auch die dort gegebenen Hinweise zur Verwaltung der Zugänge. |
Nachdem Sie die Zugänge erfolgreich erstellt haben, erhalten Sie dort pro Zugang die API-Credentials: Client ID und Client Secret | Note |
|---|
Die API-Credentials können als “read-only” oder “read-and-write” eingerichtet werden. Bei einem “read-and-write”-Modus können die Livedaten beeinflusst - geändert/gelöscht - werden. Aus diesem Grund sollten diese Credentials für “read-and-write”-Zugänge nur an vertrauenswürden Dritte weitergegeben werden. Wird Dritten der API-Zugang durch den oder die Kund:in zur Verfügung gestellt, wird empfohlen, dass der oder die Kund:in eigenständig mit diesen Dritten einen AVV (Vertrag zur Auftragsverarbeitung) abschließt. Über die Benutzer-API können nutzerbezogene Daten bezogen und (bei read-and-write) auch verändert werden.
|
2. Zugang zur API Dokumentation 2.0 BETADie interaktive Entwickler-Dokumentation der PEIQ Cloud-Connect APIs kann in jedem PORTAL über die Administrations & Moderation > Sonstige > API 2.0 BETA Dokumentation ( oder über die relative URL /admin/api ) erreicht werden. Sie finden dort interaktive Dokumentationen. Die Dokumentationen können dort dann als Open-API-Spezifikation zur Verwendung mit verschiedenen REST-Clients (z. B. Postman) heruntergeladen werden. Weitere Details (z. B. auch zur Try-it-out-Funktion) finden Sie unter API 2.0 Dokumentation PORTAL. 3. AutorisierungBei der Zugangskontrolle handelt es sich um eine Implementierung nach dem OAuth V2 Standart. Auf die Details des Protokolls wird im Folgenden nicht eingegangen, stattdessen wird anhand von Beispielen demonstriert, wie die API zum Anfordern von Access Token verwendet werden kann. Scope | N/A | Bundle Prefix | /oauth/v2 | Beispiel URL | /oauth/v2/token |
DateistrukturenAccesToken| Code Block |
|---|
{
"access_token": <string>, // Das Access Token
"expires_in": <int>, // Zeitraum in Sekunden, die das Token gültig ist
"token_type": <string>, // i.d.R. "bearer"
"scope": <string> // Liste der zugewiesenen Scopes, mit Leerzeichen getrennt
} |
WorkflowDas Anfordern von Access Token über die client_credentials erfordert die obigen Client ID und Client Secret. Die Methode ähnelt dem Benutzer-Login mit Benutzername und Passwort, es wird aber keine Session initialisiert und das Access Token ist auch nicht an einen oder eine Benutzer:in gebunden. | Note |
|---|
Achtung: Da diese Access Token mit System-Rechten ausgestattet und dementsprechend sehr mächtig sind, sollten sie niemals das Backend verlassen oder über unsicheren Wege verschickt werden. |
Methode: | | Parameter: | grant_type Muss immer den Wert client_credentials haben
client_id Die Client / Public ID
client_secret Das Secret (Passwort)
| Rückgabewert: | |
| Note |
|---|
Es wird bei jedem GET Request ein neues Token erstellt, auch wenn das zuvor angeforderte noch gültig ist. Um unnötige Requests zu vermeiden, sollten einmal angeforderte Token trotzdem so lange verwendet werden, wie sie gültig sind. |
4. Verwenden der APIBasis URL | Code Block |
|---|
https://domain.tld/api/v2 |
Alle API-Requests müssen über HTTPS ausgeführt werden. Requests über HTTP werden fehlschlagen. API-Requests ohne Autorisierung werden ebenfalls fehlschlagen. Weiterführende Hinweise und ergänzende Funktionen finden Sie auch auf den Seiten der Knowledge Base: |