Files
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

100 lines
3.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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: `<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:**
```json
{
"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
```bash
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:
```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.