Überblick & Authentifizierung
CollMap hat eine RESTful HTTP-API (gebaut mit Fastify) für Räume, Marker, Ebenen, Uploads, Kommentare und Exporte. Fast alles, was Sie in der App tun können, geht auch über HTTP — am nützlichsten: einen einzelnen Raum aus einem Skript steuern, mit einem auf diesen Raum beschränkten Token.
Basis-URL
Abschnitt betitelt „Basis-URL“Alle Endpunkte werden vom Ursprung der App ausgeliefert:
https://collmap.com(Läuft der Stack lokal, liegt der API-Server unter http://localhost:3001.)
Zwei Wege der Authentifizierung
Abschnitt betitelt „Zwei Wege der Authentifizierung“Jeder geschützte Endpunkt erwartet ein Bearer-Token im Header Authorization:
Authorization: Bearer <token>Es gibt zwei Arten von Token:
1. Eine Benutzersitzung (JWT)
Abschnitt betitelt „1. Eine Benutzersitzung (JWT)“Um als Sie selbst zu handeln — alles, was Ihr Konto darf, einschließlich der nur dem Eigentümer vorbehaltenen Vorgänge (Räume anlegen / löschen / umbenennen, Mitglieder einladen, API-Tokens ausstellen, Ihr Konto lesen). Eine angemeldete Browsersitzung tauscht ihr OIDC-Cookie gegen ein kurzlebiges JWT:
GET /api/auth/token→ { "token": "<jwt>" }. Das JWT ist kurzlebig und wird in der App automatisch erneuert.
2. Ein Raum-API-Token (cmap_…)
Abschnitt betitelt „2. Ein Raum-API-Token (cmap_…)“Für Skripte und externe Werkzeuge, die Daten in einen Raum schreiben (oder daraus lesen), ohne Browsersitzung. Sie stellen es einmal als Raumeigentümer aus und verwenden es direkt. Raum-Tokens sind auf einen Raum und auf Datenoperationen beschränkt — siehe Raum-API-Tokens.
Die Token-Beschränkung ist fail-closed
Abschnitt betitelt „Die Token-Beschränkung ist fail-closed“Ein Raum-Token wird ausschließlich auf den raumbezogenen Datenendpunkten akzeptiert, die es
ausdrücklich erreichen darf. Legen Sie es woanders vor, wird die Anfrage mit
403 api_token_not_allowed abgelehnt — so gewollt. Ein Token gegen einen anderen Raum oder ohne die
nötige Berechtigung erhält ebenfalls ein 403. Die vollständige Positivliste steht auf der Seite
Raum-API-Tokens.
WebSocket
Abschnitt betitelt „WebSocket“Die Zusammenarbeit in Echtzeit läuft über einen eigenen Yjs-WebSocket (wss://collmap.com/ws). Dieser
WebSocket ist nur für JWTs — API-Tokens haben keinen WebSocket-Weg; ihre Schreibvorgänge erreichen
das lebende Dokument über die REST-Endpunkte und verbreiten sich von dort.