Ü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://app.collmap.com(Läuft der Stack lokal, liegt der API-Server unter http://localhost:3001.)
Raum-Tokens und persönliche Schlüssel funktionieren nur in der App, in der sie erstellt wurden: Rufen Sie
die API daher unter app.collmap.com auf. collmap.com ohne app. antwortet mit einer älteren API
ohne persönliche Schlüssel.
Drei Wege der Authentifizierung
Abschnitt betitelt „Drei Wege der Authentifizierung“Jeder geschützte Endpunkt erwartet ein Bearer-Token im Header Authorization:
Authorization: Bearer <token>Es gibt drei 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.
3. Ein persönlicher API-Schlüssel (cmap_u_…)
Abschnitt betitelt „3. Ein persönlicher API-Schlüssel (cmap_u_…)“Für ein Skript oder den Connector eines KI-Assistenten, der in Ihrem Namen in all Ihren Räumen arbeitet, nicht nur in einem. Sie erstellen ihn selbst über das Benutzermenü (API-Schlüssel). Er erreicht die Räume, in denen Sie Mitglied sind, oder nur die, die Sie auswählen, mit höchstens Ihren eigenen Rechten in jedem. Außerdem kann er Ihre Räume auflisten, Ihr Profil und Ihre Nutzung lesen und einen Raum anlegen — siehe Persönliche API-Schlüssel.
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.
Ein persönlicher Schlüssel ist genauso fail-closed: Er wird auf denselben Endpunkten akzeptiert, in den Räumen, die er erreicht, dazu auf vier Routen auf Kontoebene, die unter Persönliche API-Schlüssel stehen, und überall sonst abgelehnt.
WebSocket
Abschnitt betitelt „WebSocket“Die Zusammenarbeit in Echtzeit läuft über einen eigenen Yjs-WebSocket (wss://app.collmap.com/ws). Dieser
WebSocket ist nur für JWTs — Raum-Tokens und persönliche Schlüssel haben keinen WebSocket-Weg; ihre
Schreibvorgänge erreichen das lebende Dokument über die REST-Endpunkte und verbreiten sich von dort.