Raum-API-Tokens

Ein Raum-API-Token (Präfix cmap_) lässt ein Skript oder Werkzeug auf einem Raum arbeiten, ganz ohne Browsersitzung. Es ist der empfohlene Weg, Uploads, Importe, das Anlegen von Markern und Exporte zu automatisieren.

Ein Token ausstellen

Nur der Eigentümer des Raums kann Tokens anlegen (ein Token kann keine Tokens ausstellen).

In der App

1. Gehen Sie zu Meine Räume und klicken Sie auf der Raumkarte auf die Schaltfläche API (Schlüssel).

   

2. Wählen Sie die benötigten Berechtigungen und legen Sie das Token an.

3. Kopieren Sie das Geheimnis jetzt — es wird nur ein einziges Mal angezeigt.

   

Über HTTP

Benötigt Ihr Eigentümer-JWT (siehe Überblick):

curl -X POST "$API/api/rooms/$ROOM/api-tokens" \
  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
  -d '{"name":"my-script","permissions":["read","write","upload"],"expiresInDays":30}'
# → { "token": "cmap_…", "id": "…" }   (copy the token — it is not retrievable again)

expiresInDays ist optional (1–365); lassen Sie es weg für ein Token ohne Ablauf.

Auflisten mit GET /api/rooms/$ROOM/api-tokens; widerrufen mit DELETE /api/rooms/$ROOM/api-tokens/<tokenId> (wirkt sofort). Beides ist wie das Ausstellen dem Eigentümer vorbehalten.

Aus dem Browser

Sind Sie bereits angemeldet, brauchen Sie den JWT-Schritt gar nicht — der Ausstellungs-Endpunkt akzeptiert auch Ihr Sitzungscookie, das funktioniert also direkt aus der Entwicklerkonsole in einem CollMap-Tab:

await (await fetch(`/api/rooms/${ROOM}/api-tokens`, {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'my-script', permissions: ['read', 'write', 'upload'] }),
})).json();
// → { token: "cmap_…", id: "…" }

Praktisch für ein einmaliges Token, ohne ein Skript aufzusetzen. Es ist derselbe Endpunkt und dieselbe Eigentümer-Regel — nur der Nachweis Ihrer Identität läuft anders.

Achtung

Das Token-Geheimnis wird einmal angezeigt, bei der Erstellung. Geht es verloren, widerrufen Sie es und stellen ein neues aus.

Berechtigungen

Stellen Sie ein Token nur mit dem aus, was es braucht:

Berechtigung	Erlaubt dem Token …
read	Den Raum lesen (Metadaten, Marker, Ebenen, Kommentare, Raster) und ihn exportieren
write	Importieren, Marker anlegen (einzeln + massenhaft), Marker aktualisieren und löschen, Ebenen anlegen, Ebenenstil, Kommentare und Rasterdarstellung bearbeiten
upload	Ebenendateien hochladen (GeoJSON / zip / gpkg / GeoTIFF)

Tipp

Der häufigste Fehler: Ein Token nur mit read bekommt ein 403, sobald es Daten senden will. Nehmen Sie write und/oder upload dazu, wenn Sie Daten schreiben.

Was ein Token aufrufen darf

Ein Token wird ausschließlich auf diesen raumbezogenen Datenendpunkten akzeptiert — alles andere liefert 403 api_token_not_allowed:

Berechtigung	Endpunkte
read	GET /api/rooms/:roomId, .../info, .../markers[/:markerId], .../marker-icons, .../comments, .../raster-layers[/:layerId]; GET /api/layers/:roomName; POST .../export, .../export-jobs, GET .../export-size, .../export-jobs/:id[/artifact], .../export-manifest
write	POST .../layers (GeoJSON inline), .../markers (Einzelanlage), PATCH .../markers/:markerId, DELETE .../markers/:markerId (jeder Marker — siehe unten), .../import, .../bulk-import, .../clone-jobs, .../comments[/:id/replies], PATCH .../comments/:id, DELETE .../comments/:id[/replies/:rid] (nur eigene Kommentare), PATCH /api/layers/:layerId, PATCH .../raster-layers/:id/display, POST .../markers/upload-image, POST .../marker-icons
upload	POST /api/layers/upload, .../upload-chunk, .../process-chunked
(jedes Token)	Auftragsabfrage (GET /api/layers/jobs/:id, /api/jobs/:id), Kacheln, Lesen von Ebenenobjekten, Marker-Bild-Weiterleitung

`write` erlaubt einem Token, jeden Marker zu ändern oder zu entfernen

PATCH und DELETE auf einem Marker sind nicht auf die vom Token angelegten Marker beschränkt — ein write-Token kann jeden Marker in seinem Raum bearbeiten oder löschen, auch von Hand gesetzte. (Bei Kommentaren ist es strenger: Ein Token darf nur selbst verfasste Antworten löschen.) Vergeben Sie write nur dort, wo das vertretbar ist, und nutzen Sie lieber ein eigenes Token je Integration, damit sich eines widerrufen lässt, ohne die anderen zu stören.

Was ein Token nicht darf

Dies sind Eigentümer- bzw. Admin-Vorgänge — führen Sie sie als Eigentümer aus (in der App oder mit Ihrem Eigentümer-JWT). Sie liefern absichtlich 403 api_token_not_allowed:

• Einen Raum anlegen / löschen / leeren / umbenennen; auf öffentlich schalten; Kamera- und Zeitleisteneinstellungen
• Mitglieder einladen / entfernen; Tokens ausstellen, auflisten oder widerrufen
• Konto / Verbrauch lesen (/api/account), Admin-Routen, register-user, /users/me
• Eine Ebene oder Rasterebene löschen

Der Raum muss bereits existieren (vom Eigentümer angelegt); das Token arbeitet darin.

Weiter

Zum Schnellstart für einen vollständigen Durchlauf zum Kopieren und Einfügen.