Jawengo API Belegungsdaten
Jawengo API

Authentifizierung

API Prozess

Ausgangslage: Die Lichtsteuerung im «Sportcenter Seebach» soll die Belegung der Halle abrufen. Dafür braucht das System einen Schlüssel, mit dem es sich gegenüber Jawengo ausweist. Ergebnis: Ein Benutzer besitzt einen API-Schlüssel, und das externe System kann damit Daten abrufen. Voraussetzungen: Sie gehören zur Gruppe der Administratoren (nur sie dürfen Schlüssel verwalten) und es existiert ein Benutzer für die Kopplung. Dauer: ca. 5 Minuten

Ablauf

  1. Öffnen Sie Einstellungen ▸ Benutzer & Unternehmen ▸ Benutzer und wählen Sie den Benutzer, der für die Kopplung dient.
  2. Wechseln Sie auf den Reiter API Keys (API-Schlüssel).
  3. Klicken Sie in der Liste auf Zeile hinzufügen. Bei mehreren Unternehmen wählen Sie in der Spalte Company (Unternehmen) das zugehörige Unternehmen.
  4. Klicken Sie auf Speichern. Jawengo erzeugt den Schlüssel selbst; er erscheint in der Spalte API Key und lässt sich nicht von Hand ändern.
  5. Kopieren Sie den Schlüssel in die Konfiguration des externen Systems.
  6. Senden Sie den Schlüssel bei jeder Anfrage im Header API_KEY mit, zum Beispiel so:
curl -X GET "https://<jawengo-url>/api/ping" \
     -H "API_KEY: <api-key>"

Bei gültigem Schlüssel antwortet der Server mit pong. Ein Test mit dieser Adresse zeigt, ob Schlüssel und Verbindung stimmen.

Varianten

  • Mehrere Unternehmen: Pro Benutzer und Unternehmen ist genau ein Schlüssel möglich. Der Schlüssel gilt nur für das Unternehmen, bei dem er eingetragen ist; Daten anderer Unternehmen liefert er nicht.
  • Schlüssel sperren: Entfernen Sie in der Spalte Active (Aktiv) das Häkchen. Das externe System wird danach abgewiesen.
  • Versionierte Adresse: Jede Adresse steht zusätzlich mit dem Präfix /api/v1/ zur Verfügung, zum Beispiel /api/v1/ping.

Prüfen

  • Die Anfrage an /api/ping liefert pong.
  • Bei fehlendem, ungültigem oder gesperrtem Schlüssel antwortet der Server mit dem HTTP-Status 403 (Zugriff verweigert) und liefert keine Daten.
  • Die Rechte des Benutzers bestimmen, welche Daten die Anfrage sieht. Geben Sie dem Kopplungsbenutzer daher nur die Rechte, die die Anwendung braucht, mindestens aber Portalzugriff. Mit dem Schlüssel eines Portalbenutzers sind Lesen, Reservieren (auf den eigenen Kontakt) und Stornieren möglich.

Tipp: Legen Sie für jede Kopplung einen eigenen Benutzer und damit einen eigenen Schlüssel an. So sperren Sie eine Kopplung, ohne andere zu unterbrechen.

Achtung: Der Benutzer der Kopplung braucht eine E-Mail-Adresse. Ohne sie schlägt das Stornieren einer Reservierung mit einem Fehler fehl, weil die Buchung im Verlauf der Reservierung protokolliert wird.

Achtung: Der Schlüssel ist ein Passwort. Senden Sie ihn nur über HTTPS, geben Sie ihn nicht weiter und tragen Sie ihn nicht in öffentliche Skripte oder Webseiten ein.

Verwandte Seiten

Jawengo API
Belegungsdaten