# 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). ```json { "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: `@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:** ```json { "user": { "id": "…", "username": "niklas", "display_name": "Niklas", "email": "…", "role": "member" }, "token": "", "token_type": "Bearer", "expires_in": 604800, "board": { "id": "…", "name": "Main", "collection_id": "…", "url": "https://…/board/" } } ``` **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:///magic?token=&redirect=/board/ ``` - `/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 ```bash curl -X POST https:///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: ```javascript 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.