Authentifizierung

Die TikFlow External Scan API verwendet API-Keys zur Authentifizierung. Je nach Integrationstyp wird der Key unterschiedlich übermittelt.

Integrationstypen

Beim Erstellen eines API-Keys wählen Sie den Integrationstyp:

Typ	Auth-Methode	Verwendung
Eigene Software / API	`x-api-key` Header	Eigene Anwendungen, Scripts, Terminals
TikFlow Hardware	`?key=` Query-Parameter	Physische Zutrittskontrollgeräte

💡 Warum zwei Methoden? Physische Hardware-Controller (Drehkreuze, Türcontroller) können häufig keine eigenen HTTP-Header setzen. Daher wird der API-Key bei Hardware-Integrationen als URL-Parameter übergeben.

API-Key erstellen

Schritt 1: Dashboard öffnen

Melden Sie sich im TikFlow Dashboard (opens in a new tab) an und navigieren Sie zu External API im Seitenmenü.

Schritt 2: Integrationstyp wählen

Wählen Sie zwischen:

Eigene Software / API – Für programmatische Anbindung
TikFlow Hardware – Für physische Zutrittskontrollgeräte

Schritt 3: Neuen Key anlegen

Klicken Sie auf „API-Key erstellen" und vergeben Sie einen Namen (z.B. „Haupteingang Scanner" oder „Drehkreuz Eingang Ost").

Schritt 4: Event-Scope festlegen (optional)

Sie können den API-Key auf bestimmte Events beschränken:

Option	Beschreibung
Alle Events	Der Key kann Tickets aller Ihrer Events scannen
Ausgewählte Events	Der Key kann nur Tickets der gewählten Events scannen

💡 Tipp: Für maximale Sicherheit erstellen Sie separate Keys pro Standort oder Event.

Schritt 5: Key sicher speichern

Nach dem Erstellen wird der API-Key einmalig angezeigt.

Bei „Eigene Software / API":

Kopieren Sie den API-Key und speichern Sie ihn sicher

Bei „TikFlow Hardware":

Kopieren Sie den API-Key und die angezeigten URLs:
- Card URL: /scan/hw/consume?key=IHR_KEY
- Heart URL: /scan/hw/heartbeat?key=IHR_KEY
Diese URLs können Sie direkt in Ihr Gerät eintragen

⚠️ Wichtig: Der API-Key kann später nicht mehr eingesehen werden. Teilen Sie ihn niemals öffentlich!

Authentifizierung: Eigene Software / API

Jeder API-Request benötigt den API-Key im HTTP-Header:

Header	Wert	Erforderlich
x-api-key	`{ihr_api_key}`	✅ Ja
Content-Type	`application/json`	✅ Ja (bei POST)

Beispiel

curl -X POST https://scan.tikflow.de/scan/consume \
  -H "x-api-key: iNQaDfEYDla...27aa8JG8k" \
  -H "Content-Type: application/json" \
  -d '{"ticketCode": "TK1.tkt_abc123.xyz789"}'

Authentifizierung: TikFlow Hardware

Hardware-Geräte übermitteln den API-Key als URL-Query-Parameter:

https://scan.tikflow.de/scan/hw/consume?key=IHR_API_KEY

Das Gerät sendet den QR-Code-Inhalt in seinem eigenen Datenformat – TikFlow erkennt das Gerätemodell automatisch und verarbeitet den Request entsprechend.

ℹ️ Die vollständige Konfigurationsanleitung finden Sie unter Hardware-Integration.

Event-Scope

Der Event-Scope bestimmt, welche Events mit einem API-Key gescannt werden können – unabhängig vom Integrationstyp.

Wie funktioniert es?

Das Event wird automatisch aus dem Ticket-Code ermittelt
Die API prüft, ob der verwendete Key Zugriff auf dieses Event hat
Bei fehlendem Zugriff wird 403 Forbidden zurückgegeben

Beispiel: Key ohne Zugriff

{
  "valid": false,
  "status": "rejected",
  "reason": "event_not_allowed",
  "message": "API-Key hat keinen Zugriff auf dieses Event"
}

API-Key verwalten

Key bearbeiten

Im Dashboard können Sie jederzeit:

Den Namen ändern
Den Event-Scope anpassen
Den Key aktivieren/deaktivieren

Key löschen

Gelöschte Keys werden sofort ungültig. Alle Requests mit diesem Key erhalten 401 Unauthorized.

Limits

Limit	Wert
Max. API-Keys pro Organisation	3
Anfragen pro Sekunde pro Key	50
Anfragen pro Monat pro Key	500.000

Sicherheitshinweise

✅ Do	❌ Don't
API-Key serverseitig speichern	Key im Frontend-Code verwenden
Separate Keys pro Standort	Einen Key für alles nutzen
Keys regelmäßig rotieren	Alte Keys nicht löschen
HTTPS verwenden	HTTP-Requests senden
Hardware-URLs nur am Gerät konfigurieren	URLs in öffentlichen Dokumenten teilen

ℹ️ Bei Verdacht auf Kompromittierung: Löschen Sie den Key sofort im Dashboard und erstellen Sie einen neuen.

Übersicht Endpoints