Zum Inhalt springen
DE

Ü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.

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.

Jeder geschützte Endpunkt erwartet ein Bearer-Token im Header Authorization:

Authorization: Bearer <token>

Es gibt drei Arten von Token:

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.

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.

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.

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.

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.