API-Keys

API-Keys ermöglichen es externen Systemen, sich an der Fynex REST API für Machine-to-machine-Integrationen zu authentifizieren. Jeder Key ist auf bestimmte Berechtigungen (Scopes) beschränkt und Ihrer Organisation zugeordnet.

API-Key anlegen

1. Öffnen Sie Einstellungen > Integrationen.
2. Im Bereich API-Keys klicken Sie auf API-Key erstellen.
3. Geben Sie einen aussagekräftigen Namen ein (z. B. „CRM Sync“ oder „Reporting Pipeline“).
4. Wählen Sie die Scopes, die Ihre Integration benötigt (siehe Tabelle unten).
5. Optional setzen Sie ein Ablaufdatum. Keys ohne Ablauf bleiben gültig, bis sie widerrufen werden.
6. Klicken Sie auf Erstellen.

WARNING

Der vollständige API-Key wird nur einmal angezeigt. Kopieren Sie ihn sofort und speichern Sie ihn sicher (z. B. in einem Secrets-Manager oder als Umgebungsvariable). Ein späteres erneutes Anzeigen ist nicht möglich.

Scopes

Jeder Scope erlaubt einen bestimmten Satz von API-Operationen. Vergeben Sie nur die Scopes, die Ihre Integration wirklich braucht.

Scope	Beschreibung
accounts:read	Accounts auflisten und lesen
accounts:write	Accounts anlegen und aktualisieren
contacts:read	Kontaktinformationen auflisten und lesen
contacts:write	Contacts anlegen und aktualisieren
payments:write	Zahlungen gegen Accounts registrieren
import	Bulk-Import von Accounts über den Import-Endpoint
export	Accounts und Interaction-Daten exportieren
webhooks:manage	Webhook-Subscriptions anlegen, aktualisieren und löschen

API-Key verwenden

Fügen Sie den Key bei jeder HTTP-Anfrage in den Header X-API-Key ein:

curl -H "X-API-Key: fynex_k_abc123..." \
     https://api.fynex.solutions/api/v1/accounts

Alle API-Responses nutzen übliche HTTP-Statuscodes. 401 bedeutet: Key fehlt, ist ungültig oder abgelaufen. 403 bedeutet: Der Key hat nicht den erforderlichen Scope für die angeforderte Operation.

Rate Limits

Anfragen mit API-Key sind auf 100 Requests pro 15-Minuten-Fenster begrenzt. Bei Überschreitung liefert die API 429 Too Many Requests mit Header Retry-After, der angibt, wann Sie fortfahren können.

Key widerrufen

1. Öffnen Sie Einstellungen > Integrationen.
2. Suchen Sie den Key in der Liste API-Keys.
3. Klicken Sie auf Widerrufen und bestätigen Sie.

Widerrufene Keys sind sofort ungültig. Anfragen mit einem widerrufenen Key erhalten 401.

Best Practices

• Least Privilege — Nur die Scopes vergeben, die Ihre Integration wirklich benötigt.
• Regelmäßig rotieren — Neue Keys anlegen und alte nach einem festen Rhythmus widerrufen (z. B. alle 90 Tage).
• Niemals Keys ins Repository committen — In Umgebungsvariablen oder einem Secrets-Manager speichern.
• Separate Keys pro Integration — Bei Kompromittierung einer Integration können Sie nur deren Key widerrufen.
• Ablaufdaten setzen — Für temporäre Integrationen oder Zugang von Dienstleistern ein Ablaufdatum, damit der Key automatisch endet.
• Nutzung prüfen — Die API-Key-Liste regelmäßig prüfen und ungenutzte Keys widerrufen.

TIP

Wenn ein API-Key versehentlich offengelegt wurde, widerrufen Sie ihn sofort unter Einstellungen > Integrationen und legen Sie einen Ersatz an.