festiware API v2: Eigene Integrationen anbinden (Work in Progress)

Hinweis: Work in Progress. Die festiware API v2 befindet sich im Aufbau. Sie wird in den nächsten Monaten um weitere Endpunkte erweitert, und kleinere strukturelle Änderungen sind möglich. Diese Seite wird laufend aktualisiert.

Mit der festiware API v2 verbindest du eigene Tools und Automatisierungen direkt mit deiner festiware-Instanz — zum Beispiel eine Festival-App, die Ticket-Codes abruft, einen n8n-Workflow, der Personen anlegt, oder ein eigenes Skript für Auswertungen. Die API ist projektbezogen und deckt unter anderem Personen, Gruppen, Ticketarten, Ticket-Codes und Workflow-Übergänge ab.

Die vollständige technische Referenz mit allen Endpunkten findest du unter developers.festiware.eu.

Einen API-Benutzer anlegen

Jede Integration meldet sich mit einem eigenen API-Benutzer an — nicht mit deinem persönlichen Login. So vergibst du Berechtigungen gezielt pro Integration und kannst den Zugang jederzeit entziehen, ohne dein eigenes Konto anzufassen.

Öffne im Admin-Bereich die Übersicht API-Benutzer und lege einen neuen Benutzer an.
Vergib einen sprechenden Namen, z. B. den Namen des Tools oder der App.
Wähle die Rollen aus, die die Integration braucht. Vergib nur die Rechte, die sie wirklich benötigt.
Optional: Trage die Redirect URI deines Tools ein (siehe Die Redirect URI verstehen). Das Feld lässt sich auch später jederzeit ändern.

Beim Speichern erstellt festiware automatisch alles, was für die Verbindung nötig ist — einen OAuth2-Client und ein Login-Passwort.

API-Benutzer vom Typ Check-In App sind Geräte-Logins für die festiware Check-In App und haben mit der API v2 nichts zu tun. Wie du die App einrichtest, steht unter Wie funktioniert das Einlösen der Tickets vor Ort?

Zugangsdaten herunterladen

Führe am API-Benutzer die Aktion Zugangsdaten herunterladen aus. Du erhältst eine Textdatei mit allem, was dein Tool braucht: Login (E-Mail und Passwort), Client ID, Client Secret, die OAuth2-URLs, die Redirect URI — plus Kurzanleitungen für n8n und Postman.

Behandle die Datei wie ein Passwort: sicher im Passwort-Manager ablegen und nicht unverschlüsselt per E-Mail weitergeben.

Die Redirect URI verstehen

Beim Verbinden stolpern viele über die Redirect URI — dabei gelten nur zwei Regeln:

Sie muss nicht auf einen erreichbaren Server zeigen. Sie ist lediglich die Adresse, an die der Browser nach dem Login weitergeleitet wird — Tools wie Postman fangen diese Weiterleitung lokal ab und rufen die Adresse nie auf.
Die in deinem Tool eingetragene Callback-URL muss exakt mit der Redirect URI des API-Benutzers übereinstimmen — gleiches Schema, gleicher Host, gleicher Pfad.

Stimmen die beiden Werte nicht überein, schlägt der Login mit einem Redirect-Fehler fehl. Du kannst die Redirect URI jederzeit direkt am API-Benutzer ändern; die Änderung wirkt sofort, Passwort und Client Secret bleiben dabei gültig.

Mit n8n verbinden

Lege in n8n einen neuen Credential vom Typ OAuth2 API an.
Übertrage die Werte aus der heruntergeladenen Datei: Grant Type Authorization Code, Authorization URL, Access Token URL, Client ID und Client Secret. Das Feld Scope bleibt leer.
Klicke auf Connect. Melde dich im Popup mit E-Mail und Passwort des API-Benutzers an — nicht mit deinem eigenen festiware-Login.
Bestätige die Zustimmungsseite.

n8n zeigt danach Connected an und erneuert die Tokens von selbst — die Verbindung ist damit dauerhaft eingerichtet.

Mit Postman oder eigenem Code verbinden

Die Zugangsdaten sind ein Standard-OAuth2-Client (Authorization Code Grant). Jedes Tool und jede Programmiersprache mit Unterstützung für diesen Flow funktioniert — n8n ist nur der häufigste Fall.

So verbindest du Postman:

Öffne im Request oder in der Collection den Tab Authorization und wähle Typ OAuth 2.0, Grant Type Authorization Code.
Übertrage aus der heruntergeladenen Datei: Callback URL (= Redirect URI), Auth URL, Access Token URL, Client ID und Client Secret. Stelle Client Authentication auf Send client credentials in body.
Lass den Schalter Authorize using browser ausgeschaltet. Ist er an, ersetzt Postman deine Callback-URL durch einen eigenen Postman-Server — sie stimmt dann nie mit der Redirect URI überein, und der Login schlägt immer fehl.
Klicke auf Get New Access Token und melde dich mit E-Mail und Passwort des API-Benutzers an.

Postman hängt den Token danach automatisch an jeden Request an. Ausführliche Beispiele inklusive curl findest du unter developers.festiware.eu.

Token-Laufzeiten und Zugangsdaten zurücksetzen

Ein Access Token ist 1 Stunde gültig. n8n holt sich automatisch einen neuen; in Postman klickst du einfach erneut auf Get New Access Token.
Der Refresh Token ist 1 Jahr gültig. Danach verbindest du dich einmal neu.
Wenn das Client Secret in falsche Hände geraten ist oder du den Zugang rotieren willst: Führe am API-Benutzer die Aktion Zugangsdaten zurücksetzen aus. Der alte Client und das alte Passwort sind sofort ungültig. Lade danach die neuen Zugangsdaten herunter und richte die Verbindung im Tool neu ein.

Damit behältst du die volle Kontrolle darüber, wer über die API auf deine Instanz zugreift — pro Integration, jederzeit widerrufbar.