Wie funktioniert die Sicherheit der API?

Für den Webservice gelten verschiedene Sicherheitsniveaus. Es gibt öffentliche Datensammlungen und Methoden sowie gesicherte Sammlungen und Methoden. Dies wird auf den verschiedenen Seiten der Anleitungen angegeben. Bei gesicherten Methoden muss angemeldet sein und der angemeldete Client muss die erforderlichen Rechte besitzen.

Die verschiedenen Niveaus erläutert:

• Anonyme Nutzung - die Methoden, die öffentlich sind, können ohne jegliche Form der Authentifizierung aufgerufen werden. Meistens sind dies Methoden, die Daten verwenden, die auf der Website ebenfalls öffentlich sind. Dies betrifft beispielsweise das Abrufen der verfügbaren Objekte.
  Hinweis: Durch das Einstellen eines API-Keys werden die anonymen Aufrufe gesichert. Nachdem der API-Key eingestellt wurde, muss dieser bei allen anonymen Abfragen übergeben werden.
• Benutzerniveau - der Benutzer muss angemeldet sein und arbeitet mit seinen/ihren eigenen Daten. Die Anmeldung erfolgt über die REST-Schnittstelle, siehe die user-Entität. Für einen derartigen Benutzer sind keine Profile erforderlich. Dies ist vergleichbar mit einer Website, in der ein „persönlicher Bereich“ enthalten ist. Beispielsweise die Anzeige der eigenen Daten oder einer Liste mit Buchungen, die der Benutzer selbst erstellt hat.
• Administratorniveau - der Benutzer muss angemeldet sein und muss ein Autorisierungsprofil besitzen. Abhängig von den in diesem Profil verfügbaren Rechten hat der Benutzer die Möglichkeit, Daten abzurufen und/oder zu manipulieren. Auf diese Weise könnte eine vollständige Administrator-Anwendung gebaut werden.

Methoden der Authentifizierung

Die Benutzerniveaus - höher als die anonyme Nutzung - sind auf verschiedene Weisen erreichbar.

• Anmeldung über die API
  Die API selbst kann verwendet werden, um eine Sitzung zu erstellen.
  Dies geschieht über die API - User.
  Verwenden Sie hierfür die Methode POST user/login. Achten Sie auf die Verwendung des Attributs admin. Setzen Sie dieses auf true für eine Administrator-Anmeldung.
• Basic Auth
  Eine Methode, die bei REST-APIs häufig verwendet wird.
  Für allgemeine Informationen siehe: Open API
  Verwenden Sie den Benutzernamen + das Passwort, mit dem Sie sich auch im Verwaltungspanel anmelden.
• Oauth 2
  Für allgemeine Informationen siehe: Open API
  Detailschritte sind hier beschrieben.

Authentifizierung ab API-Version 2

Alles oben beschreibt Version 1 des Webservice. Ab Version 2 — die Version, die Sie mit einem Präfix in der URL wählen, api/rest/v2/… — gilt, dass jeder Aufruf eine Identität hat. Anonyme Nutzung und Basic Auth gibt es dort nicht mehr. An Version 1 ändert sich nichts: bestehende Integrationen funktionieren unverändert weiter.

Es gibt zwei Wege, diese Identität mitzugeben:

• Ein API-Schlüssel pro Benutzer — die übliche Wahl für eine Server-zu-Server-Integration. Im Header X-APIKEY mitgeben. Siehe Wie funktioniert ein API-Schlüssel?
• Ein Zugriffstoken — die Wahl für eine App. Ein Mitarbeiter meldet sich auf einem Gerät an, und das daraus entstehende Token wird als Authorization: Bearer <token> mitgesendet. Das Token trägt die Rechte dieses Mitarbeiters, genau wie ein Schlüssel.

Ein Token fordern Sie mit POST user/auth an (Benutzername und Passwort) und erneuern es mit POST user/refresh. Eine App, die mit einem Kopplungscode mit einer Umgebung verbunden wird, verwendet POST app/pair-exchange. Diese drei Aufrufe benötigen selbst keinen Schlüssel und kein Token — sie geben ja gerade eines aus — und sind deshalb pro IP-Adresse deutlich strenger begrenzt als der Rest der API.

Mit GET user/me?rights=1 fragen Sie ab, wer der Aufrufer ist und welche Rechte er hat. Das ist der schnellste Weg herauszufinden, warum ein Aufruf mit 403 antwortet.