- POST /api/external/session: bridge auth via X-API-Key, JIT user provisioning - GET /api/external/health: capability report - /magic frontend route: consumes ?token= JWT, redirects - docs/EXTERNAL-API.md: bridge contract spec
3.8 KiB
Open RefBoard — External Integration API (v1)
Generische Schnittstelle für Bridges: externe Systeme (AYON, Nextcloud, Skripte, …) authentifizieren sich per API-Key und melden Nutzer zu RefBoard-Sessions an. RefBoard ist dabei bridge-agnostisch — jede Bridge ist ein dünner Client dieser Spec.
Voraussetzung
REFBOARD_API_KEY muss in der RefBoard-.env gesetzt sein (Header X-API-Key).
Ohne Key antwortet die API mit 503 API key not configured on server.
Endpoints
GET /api/external/health
Liveness + Capability-Report. Kein Auth nötig? Doch: API-Key (Konsistenz).
{ "status": "ok", "service": "refboard", "open_refboard": true, "api_version": 1, "users": 12 }
POST /api/external/session
Stellt sicher, dass der Nutzer existiert (Auto-Provisionierung), und stellt ein Login-JWT aus.
Request:
| Feld | Typ | Pflicht | Bedeutung |
|---|---|---|---|
user_name |
string | ✅ | Identität aus dem Quellsystem. Wird zu Username sanitisiert (a-z0-9_-), auch Display-Name. Pflicht. |
user_email |
string | – | Externe E-Mail. Default: <username>@bridges.local (konfigurierbar via EXTERNAL_BRIDGE_EMAIL_DOMAIN). |
board_id |
string | – | Direkt auf dieses Board landen. |
collection_name |
string | – | Collection per Name suchen; wird bei Bedarf erzeugt (User wird Owner). |
collection_id |
string | – | Collection per ID (keine Auto-Erzeugung; 404 wenn fehlend). |
board_name |
string | – | Board-Name innerhalb der Collection (Default "Main"; wird bei Bedarf erzeugt). |
role |
"member" | "admin" |
– | Rolle nur für neu angelegte Nutzer (Default member). |
Antwort 200:
{
"user": { "id": "…", "username": "niklas", "display_name": "Niklas", "email": "…", "role": "member" },
"token": "<JWT>",
"token_type": "Bearer",
"expires_in": 604800,
"board": { "id": "…", "name": "Main", "collection_id": "…", "url": "https://…/board/<id>" }
}
Fehler: 400 (user_name fehlt), 401 (API-Key), 403 (User deaktiviert),
404 (board_id/collection_id unbekannt), 409 (E-Mail-Konflikt bei Provisionierung),
503 (API-Key nicht konfiguriert).
Magic-Login (Browser)
Bridge schickt den Nutzer an:
https://<refboard>/magic?token=<JWT>&redirect=/board/<boardId>
/magicvalidiert den Token via/api/auth/me, speichert ihn und leitet weiter.redirectoptional (Default/).- Token läuft nach
JWT_EXPIRES_INab (Default 7d).
Provisionierungs-Regeln
- Neuer
user_name→ Konto wird automatisch angelegt (Zufalls-Passwort, damit kein direkter Passwort-Login möglich ist; Reset nur via Admin). - Wiedererkennung anhand Username (sanitisierter
user_name). - E-Mail-Kollision (
user_emailexistiert, aber anderer Username) →409, keine stillen Zusammenführungen. - Existierende Nutzer: keine Rollen-Änderung durch Bridges (mindestens
rolenur bei Neuanlage).
Bridge-Minimalbeispiel
curl -X POST https://<refboard>/api/external/session \
-H "X-API-Key: $REFBOARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"user_name": "niklas", "collection_name": "amberflash", "board_name": "Refs"}'
# → { token, board.url } → Browser öffnen: board.url + "?token=" … eigentlich: /magic?token=…
Login-URL bauen:
const loginUrl = `${session.board.url.replace(/\/board\/(.+)$/, '/magic')}?token=${session.token}&redirect=/board/${session.board.id}`;
Konventionen für Bridges
- Bridge kennt nur: RefBoard-URL +
REFBOARD_API_KEY. Kein User-Passwort-Handling. - Bridge mappt ihre Identität auf
user_name(stabil & eindeutig pro Quelle, z.B. AYON-Username bzw. Nextcloud-UserId). - Board-Auswahl:
collection_namepro Quellprojekt (AYON: Projektname, Nextcloud: Ordnername) — RefBoard erzeugt sie on-demand.