Authentifizierung
Öffentliche Inhalte, also Informationen, die bereits auf der Webseite veröffentlicht sind, können ohne Authentifizierung einfach abgerufen werden. Schreibzugriff ist ohne Authentifizierung nicht möglich.
API-Zugänge sind immer mit Schnittstellen verknüpft. Über Schnittstellen werden gleichartige API-Zugänge (gleicher Zweck, gleiche Berechtigungen) zusammengefasst. Jeder API-Zugang ist zudem mit einem Kontakt verknüpft.
Der verknüpfte Kontakt wird dann bei Schreibzugriff bei „erstellt von“, „zuletzt bearbeitet von“ sowie im Schreibvorlauf und in den Aktionen angezeigt. Um die Zugriffe durch Fremdsoftware besser nachvollziehen zu können, empfehlen wir daher, einen Kontakt für jede eingesetzte Fremdsoftware mit API-Zugriff zu erstellen.
Bei Verdacht auf Missbrauch eines API-Zugriffs, etwa wenn ein API-Token gestohlen wurde/abgeflossen ist, kann der zugehörige Zugang deaktiviert werden. Der Zugriff ist dann sofort nicht mehr möglich.
Der Token muss dann in einem Bearer-Auth-Header bei jeder Anfrage angegeben werden (vgl. RFC 6750):
Authorization: Bearer Ihr_Token_hierDer API-Zugang erhält alle Berechtigungen aus dem mit der Schnittstelle verknüpften Berechtigungsset. Schränken Sie nach Möglichkeit den Zugriff auf Daten und Funktionen durch API-Zugänge so weit wie möglich ein. Sollte ein API-Token verloren gehen, kann so der mögliche Schaden eingegrenzt werden.
Mithilfe einer Schnittstellenvorlage
Für häufig verwendete Fremdsoftware, die API-Zugriff benötigt, liefern wir Schnittstellenvorlagen aus. Die nötigen Berechtigungen und Abfragen sind dann schon von uns erstellt und hinterlegt.
Um den authentifizierten Zugriff auf eine solche Fremdsoftware auf die API zu ermöglichen, gehen Sie wie folgt vor:
- Navigieren Sie zu den Schnittstellen, indem Sie „Schnittstellen“ in die globale Suche eingeben.
- Überprüfen Sie, ob die gewünschte Schnittstelle ggf. schon erstellt wurde. Wenn ja: Klicken Sie auf die bereits erstellte Schnittstelle und springen Sie zu Schritt 4.
- Erstellen Sie mit einem Klick auf die drei Punkte neben „Schnittstelle erstellen“ eine Schnittstelle von einer Vorlage, suchen nach der Vorlage und klicken auf „Erstellen“.
- Fügen Sie bei Bedarf das Objekt (Applikation) Zugänge hinzu, und erstellen Sie darin einen neuen Zugang.
- Geben Sie dem Zugang einen aussagekräftigen Namen, etwa „API-Zugang für Name der Fremdsoftware“. Gerade, wenn etwa mehrere Zugänge für mehrere Endgeräte erstellt werden, ist dies wichtig.
- Hinterlegen Sie im Feld Kontakt den Kontakt, für den der Zugang gelten soll. Der Kontakt muss an dieser Stelle bereits erstellt sein. Wenn nicht, erstellen Sie ihn vorher in einem zweiten Tab/Fenster.
- Jetzt wird ein API-Token generiert, mit dem Zugriff auf die API möglich ist. Der Token wird nur einmal angezeigt. Kopieren Sie ihn diesen in die entsprechende Stelle der Fremdsoftware bzw. speichern Sie diesen ab.
Ohne Vorlage (individuelle Schnittstelle)
Wenn wir keine Schnittstellenvorlage für eine (Art von) Fremdsoftware/Anbindung anbieten, kann auch eine individuelle API-Schnittstelle mit Zugängen erstellt werden. Gehen Sie dazu wie folgt vor:
- Navigieren Sie zu den Schnittstellen, indem Sie „Schnittstellen“ in die globale Suche eingeben.
- Überprüfen Sie, ob die gewünschte Schnittstelle ggf. schon erstellt wurde. Wenn ja: Klicken Sie auf die bereits erstellte Schnittstelle und springen Sie zu Schritt 5.
- Erstellen Sie mit einem Klick auf „Schnittstelle erstellen“ eine neue Schnittstelle. Vergeben Sie einen aussagekräftigen Namen (Name der Fremdsoftware/Art der Anbindung) und die Art „API“.
- Hinterlegen Sie im Feld Berechtigungsset ein Berechtigungsset für die API-Zugänge. Es empfiehlt sich, für jede Schnittstelle ein eigenes Berechtigungsset zu erstellen (dies kann auch von einem vorhandenen Berechtigungsset kopiert werden). Vergeben Sie nur die Berechtigungen, die tatsächlich benötigt werden.
- Fügen Sie bei Bedarf das Objekt (Applikation) Zugänge hinzu, und erstellen Sie darin einen neuen Zugang.
- Geben Sie dem Zugang einen aussagekräftigen Namen, etwa „API-Zugang für Name der Fremdsoftware“. Gerade, wenn etwa mehrere Zugänge für mehrere Endgeräte erstellt werden, ist dies wichtig.
- Hinterlegen Sie im Feld Kontakt den Kontakt, für den der Zugang gelten soll. Der Kontakt muss an dieser Stelle bereits erstellt sein. Wenn nicht, erstellen Sie ihn vorher in einem zweiten Tab/Fenster.
- Jetzt wird ein API-Token generiert, mit dem Zugriff auf die API möglich ist. Der Token wird nur einmal angezeigt. Kopieren Sie ihn diesen in die entsprechende Stelle der Fremdsoftware bzw. speichern Sie diesen ab.