Publish container image / build-and-push (push) Canceled after 0s
- 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
100 lines
3.8 KiB
Markdown
100 lines
3.8 KiB
Markdown
# 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.
|