EntwicklerREST API

API-Connector

Wo ein Mandant Ende-zu-Ende verschlüsselt, gibt die API die Namen der Teilnehmer:innen nur versiegelt heraus. Eine Integration, die die Kryptografie nicht selbst übernehmen kann, spricht stattdessen mit dem Connector: einem Docker-Image, das neben ihr läuft, den Schlüssel des Service-Accounts hält und die API in Ihrem eigenen Netz mit Namen im Klartext anbietet.

Der Connector übernimmt, was Ende-zu-Ende-Verschlüsselung beschreibt. Ihre Integration behält ihr Token und ihre Aufrufe; nur ihre Basis-URL ändert sich.

Was der Connector tut

Aufruf der Integration	Was der Connector tut
`GET /participants`, `GET /participants/{uuid}`	öffnet die Namen in `firstname`, `lastname` und `name`. Eine Teilnehmer:in, die das Team noch nicht für die Integration freigegeben hat, behält ihr Pseudonym.
`GET /participants?q=…`	ruft die Liste mit den übrigen Filtern ab, öffnet sie, filtert und sortiert sie nach Namen und teilt sie selbst in Seiten
`POST /participants` mit `firstname` und `lastname`	versiegelt sie unter einem neuen Datensatzschlüssel, für den Team-Schlüssel und den eigenen Schlüssel
`PATCH /participants/{uuid}` mit Namen	versiegelt jedes versiegelte Feld neu unter einem eigenen, neuen Datensatzschlüssel, für den Team-Schlüssel und den eigenen Schlüssel. Felder, die der Aufruf nicht schickt, nimmt er aus dem Datensatz, wie er ist; solange der Datensatz nicht für die Integration freigegeben ist, müssen dafür alle im Aufruf stehen, sonst ist die Antwort `409`.
alles andere, z. B. `/offers`	reicht es unverändert weiter

Der Connector reicht Authorization an fepli weiter, jeder Aufruf behält also die Berechtigungen seines Tokens. Ein Connector, der für einen Mandanten ohne Verschlüsselung eingerichtet ist, reicht alles unverändert durch.

Namen gehen nie im Klartext hinaus

Sobald der Emoji-Vergleich einen Team-Schlüssel festgehalten hat, richtet sich der Connector nach diesem Schlüssel, nicht danach, was fepli später sagt:

Er schickt Namen versiegelt oder gar nicht. Kann er GET /e2e nicht lesen, oder antwortet fepli, der Mandant verschlüssele nicht, lehnt er ein Schreiben mit Namen mit 503 ab und schickt nichts. Um wieder im Klartext zu arbeiten, richten Sie den Connector neu ein.
Er versiegelt mindestens firstname und lastname, dazu jedes weitere Feld, das sealedFields nennt.
Er versiegelt nur für den festgehaltenen Team-Schlüssel und den eigenen Schlüssel, unter einem Datensatzschlüssel, den er selbst erzeugt; einen Datensatzschlüssel, den fepli ihm gibt, verwendet er nie weiter. Den neuen Schlüssel geben Browser des Teams im Hintergrund wieder an die Gruppen der Veranstalter-Profile weiter.

Fehler schreibt das Image in das Log des Containers, nicht in seine Antworten.

Eine Suche mit ?q= liefert ihre Seite mit den Headern X-Total-Count, X-Total-Pages, X-Page und X-Items-Per-Page.

Das Image

ghcr.io/ferienpass/fepli-api-connector, für amd64 und arm64. Tags: latest, eine Version wie 1.2.3 und 5.x für den neuesten Build.

Name
FEPLI_API
Typ
string
Beschreibung
Die API von fepli, z. B. https://example.fepli.eu/api. Pflicht.
Name
FEPLI_TOKEN
Typ
string
Beschreibung
Ein Token des Service-Accounts (svc-…). Nur für enrol und status nötig; im Betrieb nutzt der Connector das Token des jeweiligen Aufrufs.
Name
FEPLI_KEY_FILE
Typ
string
Beschreibung
Wo der Schlüssel liegt. Standard: /data/fepli-key.json.
Name
PORT
Typ
integer
Beschreibung
Der Port im Container. Standard: 8080.
Name
PHP_CLI_SERVER_WORKERS
Typ
integer
Beschreibung
Wie viele Aufrufe er gleichzeitig bearbeitet. Standard: 4.

Das Volume /data enthält fepli-key.json mit dem privaten Schlüssel, lesbar nur für den Benutzer des Containers. GET /healthz antwortet 503, bis der Schlüssel bestätigt ist.

Befehl	Was er tut
`serve`	Standard: bietet die API an
`enrol`	einmalig, interaktiv (`-it`): erzeugt den Schlüssel, meldet ihn an und beantwortet den Emoji-Vergleich
`status`	zeigt den Schlüssel und ob fepli ihn bestätigt hat; Exit-Code `0`, wenn bestätigt

Einrichten

Legen Sie im Admin-Panel einen Service-Account mit den Rollen Admin und Teilnehmer:innen an und erstellen Sie ein Token dafür.
Erzeugen Sie den Schlüssel und beantworten Sie den Emoji-Vergleich, mit einem Super-Admin des Mandanten am Telefon:
Schlüssel erzeugen und Emojis vergleichen
```
docker run --rm -it -v fepli-connector:/data \
  -e FEPLI_API=https://example.fepli.eu/api \
  -e FEPLI_TOKEN=$FEPLI_TOKEN \
  ghcr.io/ferienpass/fepli-api-connector enrol
```
Der Super-Admin öffnet den Service-Account unter Einstellungen → Integrationen, wählt, was er liest, und dann Emojis vergleichen. Antworten Sie nur dann mit y, wenn beide Bildschirme dieselben 7 Emojis in derselben Reihenfolge zeigen.

Starten Sie den Connector, erreichbar nur für die Integration:

Den Connector starten

docker run -d --name fepli-connector --restart unless-stopped \
  -v fepli-connector:/data \
  -e FEPLI_API=https://example.fepli.eu/api \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/ferienpass/fepli-api-connector

Lassen Sie die Integration statt auf die Adresse von fepli auf http://127.0.0.1:8080/api zeigen.

Um den Schlüssel später zu prüfen, starten Sie das Image mit status und demselben Volume und denselben Variablen wie bei enrol.

Sicher betreiben

Wer den Connector mit dem Token des Service-Accounts erreicht, liest die Namen im Klartext. Geben Sie seinen Port nur auf dem Host der Integration oder in Ihrem internen Netz frei, nie im Internet.