Files
refboard-ayon/docs/EXTERNAL-API.md
T
Hermes 0504df49b0
Publish container image / build-and-push (push) Canceled after 0s
feat: external session API + magic login (merge from open-refboard 02750ba)
- 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
2026-10-14 10:13:54 +00:00

3.8 KiB
Raw Blame History

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>
  • /magic validiert den Token via /api/auth/me, speichert ihn und leitet weiter.
  • redirect optional (Default /).
  • Token läuft nach JWT_EXPIRES_IN ab (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_email existiert, aber anderer Username) → 409, keine stillen Zusammenführungen.
  • Existierende Nutzer: keine Rollen-Änderung durch Bridges (mindestens role nur 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

  1. Bridge kennt nur: RefBoard-URL + REFBOARD_API_KEY. Kein User-Passwort-Handling.
  2. Bridge mappt ihre Identität auf user_name (stabil & eindeutig pro Quelle, z.B. AYON-Username bzw. Nextcloud-UserId).
  3. Board-Auswahl: collection_name pro Quellprojekt (AYON: Projektname, Nextcloud: Ordnername) — RefBoard erzeugt sie on-demand.