Vocatis API 9.0 - API-Zugang Cloudserver DE SIGNO
Diese Anleitung beschreibt die Einrichtung und Nutzung eines API-Zugangs für Kunden, die Vocatis auf einem von DE SIGNO bereitgestellten Cloudserver nutzen.
Die Vocatis API ermöglicht es externen Anwendungen, auf Vocatis-Daten zuzugreifen und – abhängig von den freigeschalteten Berechtigungen – Daten zu verwalten.
1. API-Adresse
Die URL ist abhängig vom System. In der Regel ist sie unter der Basisadresse des Servers mit dem Pfad “VocatisApi” erreichbar (z.B. https://xxx.isigncloud.de/VocatisApi/ ).
2. API-Spezifikation
Die vollständige technische Beschreibung der API steht als OpenAPI-Spezifikation zur Verfügung:
https://xxxxx.de/VocatisApi/swagger/v1/swagger.json
Beispiel:
3. API-Zugang über Client ID und Client Secret
Der Zugriff auf die API erfolgt über einen OAuth-Client.
Die OpenId-Konfiguration des Servers kann unter https://xxx.de/ID/.well-known/openid-configuration abgerufen werden.
Für die Einrichtung werden benötigt:
- Client ID
- Client Secret
- gewünschte API-Berechtigung (Scope)
Client ID
Die Client ID kann vom Kunden vorgegeben werden.
Die Client ID sollte eindeutig sein und möglichst einen Bezug zur Anwendung oder zum Kunden enthalten.
Client Secret
Das Client Secret ist das vertrauliche Passwort des API-Clients.
Der Kunde kann ein eigenes Client Secret vorgeben oder DE SIGNO kann ein Secret erzeugen.
Das Client Secret darf ausschließlich innerhalb der Anwendung bzw. der sicheren Konfiguration des Kunden gespeichert werden.
5. Berechtigungen
Je nach Anwendungsfall können unterschiedliche Berechtigungen vergeben werden:
| Scope | Verwendung |
|---|---|
vocatisapi:control | Allgemeiner Benutzerzugriff |
vocatisapi:admin | Administrativer Zugriff |
vocatisapi:super | Zugriff aus Superuser-Funktionen |
identity:user-profile | Abrufen von Benutzerprofilen |
DE SIGNO schaltet nur die für den jeweiligen Anwendungsfall benötigten Berechtigungen frei.
Für reine Lesezugriffe ist grundsätzlich zu prüfen, welche Berechtigung für die benötigten Endpunkte erforderlich ist.