DevelopersREST API

API connector

Where a tenant encrypts end to end, the API hands out the names of participants only sealed. An integration that cannot do the cryptography itself talks to the connector instead: a Docker image that runs beside it, holds the service account's key, and offers the API with names in the clear on your own network.

The connector does the work End-to-end encryption describes. Your integration keeps its token and its calls; only its base URL changes.

What the connector does

Call of the integration	What the connector does
`GET /participants`, `GET /participants/{uuid}`	opens the names into `firstname`, `lastname` and `name`. A participant the team has not shared with the integration yet keeps its pseudonym.
`GET /participants?q=…`	reads the list with the other filters, opens it, filters and orders it by name, and pages it itself
`POST /participants` with `firstname` and `lastname`	seals them under a new record key, for the team key and its own key
`PATCH /participants/{uuid}` with names	seals every sealed field again under a new record key of its own, for the team key and its own key. Fields the call does not send it takes from the record as it is; while the record is not shared with the integration, that needs all of them in the call, otherwise the answer is `409`.
everything else, e.g. `/offers`	forwards it as it is

The connector passes Authorization on to fepli, so every call keeps the permissions of the token. A connector set up for a tenant that does not encrypt forwards everything untouched.

Names are never sent in the clear

Once the emoji comparison has pinned a team key, the connector goes by that key, not by what fepli says later:

It sends names sealed or not at all. If it cannot read GET /e2e, or fepli answers that the tenant does not encrypt, a write with names is refused with 503, and nothing is sent. To work in the clear again, set the connector up again.
It seals at least firstname and lastname, and every further field sealedFields lists.
It seals only for the pinned team key and its own key, under a record key it makes itself; it never reuses a record key fepli hands it. The team's browsers share the new key with the hosts' groups again in the background.

The image writes errors to the container's log and none into its answers.

A search with ?q= returns its page with the headers X-Total-Count, X-Total-Pages, X-Page and X-Items-Per-Page.

The image

ghcr.io/ferienpass/fepli-api-connector, for amd64 and arm64. Tags: latest, a version such as 1.2.3, and 5.x for the newest build.

Name
FEPLI_API
Type
string
Description
fepli's API, e.g. https://example.fepli.eu/api. Required.
Name
FEPLI_TOKEN
Type
string
Description
A token of the service account (svc-…). Needed for enrol and status only; while serving, the connector uses the token of each call.
Name
FEPLI_KEY_FILE
Type
string
Description
Where the key is kept. Default: /data/fepli-key.json.
Name
PORT
Type
integer
Description
The port inside the container. Default: 8080.
Name
PHP_CLI_SERVER_WORKERS
Type
integer
Description
How many calls it handles at once. Default: 4.

The volume /data holds fepli-key.json with the private key, readable only by the container's user. GET /healthz answers 503 until the key is confirmed.

Command	What it does
`serve`	the default: offers the API
`enrol`	once, interactively (`-it`): makes the key, registers it and answers the emoji comparison
`status`	shows the key and whether fepli has confirmed it; exit code `0` when confirmed

Set it up

In the admin, create a service account with the roles Admin and Teilnehmer:innen, and a token for it.
Make the key and answer the emoji comparison, with a super admin of the tenant on the phone:
Make the key and compare emojis
```
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
```
The super admin opens the service account under Einstellungen → Integrationen, chooses what it reads and selects Emojis vergleichen. Answer y only if both screens show the same 7 emojis in the same order.

Run the connector, reachable for the integration only:

Run the connector

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

Point the integration at http://127.0.0.1:8080/api instead of fepli's address.

To check the key later, run the image with status and the same volume and variables as for enrol.

Keep it safe

Whoever reaches the connector with the service account's token reads the names in the clear. Publish its port only on the integration's host or your internal network, never to the internet.