Authentifizierung

Die fepli-API authentifiziert mit Bearer-Tokens. Ein Token handelt entweder als Teammitglied oder als Service-Account, und es erlaubt entweder nur Lesezugriff oder Lese- und Schreibzugriff.

Ein Token senden

Setzen Sie das Token mit dem Schema Bearer in den Header Authorization:

curl https://example.fepli.eu/api/me \
  -H "Authorization: Bearer pat-3kT9wQ2mZx7LpR4vN8bYc1Hd.f0Jq…"

Ein Token beginnt mit pat- oder svc-. Darauf folgen eine Kennung mit 24 Zeichen, ein Punkt und ein Secret mit 64 Zeichen. Ein Token wird nur einmal angezeigt, nämlich beim Erstellen, und lässt sich nicht erneut abrufen. Haben Sie eines verloren, widerrufen Sie es und erstellen ein neues.

Zwei Arten von Tokens

Beide Arten können eine Bezeichnung und ein Ablaufdatum haben. Das Admin-Panel zeigt, wann jedes Token zuletzt verwendet wurde, auf fünf Minuten genau.

Lese- und Schreibzugriff

Jedes Token trägt einen Scope:

• api:read erlaubt nur GET-Anfragen.
• api:write erlaubt zusätzlich POST, PATCH und DELETE: Datensätze anlegen, ändern, löschen und durch ihren Workflow bewegen.

Den Scope wählen Sie beim Erstellen des Tokens (Nur lesen oder Lesen und schreiben). Ein Token, das nur liest, wird bei jedem POST, PATCH und DELETE abgelehnt, bevor irgendetwas anderes geprüft wird, unabhängig von den Rollen seiner Inhaber:in:

{
  "type": "/errors/403",
  "title": "An error occurred",
  "status": 403,
  "detail": "This token is read-only. Mint one with write access to change anything."
}

Für Service-Accounts gibt es eine zweite Grenze. Die Zugriffsstufe des Service-Accounts (read oder write) begrenzt jedes seiner Tokens. Ein Token, das mit Schreibzugriff erstellt wurde, kann nur lesen, wenn der Service-Account später auf read beschränkt wurde.

Mit GET /me sehen Sie die Scopes und den geltenden Zugriff eines Tokens:

{
  "scopes": ["api:read", "api:write"],
  "access": "write"
}

Öffentlicher Zugriff

Ein Teil der API braucht kein Token: GET /offers und GET /offers/{uuid} liefern die veröffentlichten Angebote der Saisons, die online sind, also die, die die öffentliche Website zeigt. Angebote, die mit einem privaten Link veröffentlicht wurden, liefert die API ohne Token nie. Anonyme Aufrufer erhalten nur die öffentlichen Felder. Die internen, etwa comment, contact oder transitions, fehlen.

Super-Admins können den öffentlichen Zugriff unter Einstellungen → Integrationen → API → Öffentlicher Zugriff ausschalten. Dann braucht jede Anfrage ein Token, und anonyme Anfragen erhalten ein 401. Die Ausnahme ist ein Aufruf der Bausteine mit einem öffentlichen Schlüssel.

Anonyme Anfragen unterliegen einem strengen Rate-Limit. Speichern Sie die Antworten bei sich zwischen.

Öffentliche Schlüssel

Ein Browser auf einer anderen Website kann den öffentlichen Zugriff nicht unverändert nutzen: Die API teilt einer fremden Seite nicht mit, dass sie die Antwort lesen darf, und anonyme Aufrufe sind pro IP-Adresse begrenzt. Für diesen Fall gibt es einen öffentlichen Schlüssel. Mit ihm rufen die Bausteine die API auf, und Sie können ihn für Ihr eigenes JavaScript verwenden.

curl -G https://example.fepli.eu/api/offers \
  -H "Origin: https://www.elmsbrueck.de" \
  -d edition=herbstferien-2026 \
  -d key=pk_9f3a2c71e4b05d18a6c2e7f0

• Ein öffentlicher Schlüssel ist kein Token. Er öffnet, was der öffentliche Zugriff öffnet, nämlich die veröffentlichten Angebote bei GET /offers und GET /offers/{uuid}, und sonst nichts. Das gilt auch, solange der öffentliche Zugriff ausgeschaltet ist. Er gehört als key in die Adresse, nicht in den Header Authorization. Eine Anfrage mit Token gilt als Anfrage des Tokens.
• Er nennt die Websites, für die er gilt. Die API beantwortet eine Seite einer solchen Website mit Access-Control-Allow-Origin, damit der Browser Ihrem Skript erlaubt, die Antwort zu lesen. Eine Seite jeder anderen Website erhält 403.
• Anfragen mit einem Schlüssel zählen für den Schlüssel, nicht für die IP-Adresse der Besucher:in.
• Solange der öffentliche Zugriff ausgeschaltet ist, muss ein Aufruf mit Schlüssel zusätzlich nennen, von welcher Website er kommt: mit dem Header Origin, der gegen die Websites des Schlüssels geprüft wird, oder mit Sec-Fetch-Site: same-origin für eine Seite der eigenen Website des Mandanten. Jeder andere Aufruf wird wie ein anonymer abgelehnt. Die zwischengespeicherte Antwort hängt von Origin und Sec-Fetch-Site ab.
• Schlüssel erstellen Sie in der App Website einbinden (Einstellungen → App-Store). Sie funktionieren nur, solange diese App eingeschaltet ist. Die App braucht die eingeschaltete App API, nicht den öffentlichen Zugriff. Ein widerrufener Schlüssel ergibt 403.

Die Prüfung der Website stützt sich auf die Header Origin und Sec-Fetch-Site, die ein Browser sendet. Beide setzt der Aufrufer selbst, und ein Schlüssel ist öffentlich. Betrachten Sie den Schlüssel deshalb als Angabe, wer einbettet, und nicht als Geheimnis. Ein Browser, der kein Sec-Fetch-Site sendet (Safari vor 16.4), kann bei ausgeschaltetem öffentlichem Zugriff keinen Baustein von der eigenen Website des Mandanten laden.

Ältere Tokens

Persönliche Tokens, die mit früheren Versionen von fepli erstellt wurden, tragen den alten Scope api:offer:read. Sie funktionieren weiter, aber nur für GET /offers und GET /offers/{uuid}. Jeder andere Endpunkt antwortet mit 403. Um den Rest der API zu nutzen, erstellen Sie ein neues Token.

Wenn die Authentifizierung fehlschlägt

Ein Token funktioniert nur für den Mandanten, in dem es erstellt wurde. In einer Installation mit mehreren Mandanten ist das Token eines Mandanten allen anderen unbekannt.

Tokens sicher aufbewahren

• Legen Sie ein Token nie in Browser- oder App-Code ab. Dort kann es jeder lesen. Um Angebote öffentlich zu zeigen, brauchen Sie kein Token. Für alles andere rufen Sie die API von Ihrem Server aus auf.
• Geben Sie jeder Integration ein eigenes Token, mit einer Bezeichnung, die Sie später wiedererkennen. Dann können Sie eines widerrufen, ohne die anderen zu stören.
• Bevorzugen Sie Tokens mit Lesezugriff. Die meisten Integrationen und jeder Support-Agent, der nur Fragen beantwortet, kommen mit Lesezugriff aus.
• Legen Sie ein Ablaufdatum fest für Tokens, die nur vorübergehend gelten sollen.
• Widerrufen Sie ein Token im Admin-Panel, sobald Sie es nicht mehr brauchen oder es möglicherweise offengelegt wurde. Der Widerruf wirkt sofort.