Zum Inhalt springen
DE

Persönliche API-Schlüssel

Ein persönlicher API-Schlüssel (Präfix cmap_u_) lässt ein Skript oder den Connector eines KI-Assistenten in Ihrem Namen in den Räumen arbeiten, in denen Sie Mitglied sind — ohne Anmeldung im Browser und ohne ein Raum-Token pro Raum. Er kann außerdem Ihre Räume auflisten, Ihr Profil und Ihre Speichernutzung lesen und einen Raum anlegen.

Raum-Token (cmap_…) Persönlicher Schlüssel (cmap_u_…)
Erstellt von dem Eigentümer des Raums, für einen Raum Ihnen, für sich selbst
Erreicht diesen einen Raum jeden Raum, in dem Sie Mitglied sind, oder nur die Räume, die Sie auswählen
Rechte in einem Raum die Berechtigungen des Tokens die Berechtigungen des Schlüssels, nie mehr als Ihre eigene Rolle dort
Kontoebene nichts Ihre Räume, Ihr Profil und Ihre Nutzung, einen Raum anlegen
  1. Öffnen Sie das Benutzermenü (oben rechts) und wählen Sie API-Schlüssel.

  2. Benennen Sie den Schlüssel, kreuzen Sie seine Berechtigungen an, wählen Sie, wann er abläuft (7 bis 365 Tage, standardmäßig 90), und wählen Sie Alle meine Räume oder Nur diese Räume.

  3. Wählen Sie Schlüssel erstellen und kopieren Sie den Schlüssel sofort — er wird nur einmal angezeigt.

  • Ein Ablaufdatum ist Pflicht: 1 bis 365 Tage, 90, wenn Sie nichts angeben.
  • Höchstens 10 aktive Schlüssel. Ein elfter antwortet mit 409 too_many_keys: Widerrufen Sie zuerst einen.
  • Die Raumliste steht fest, sobald der Schlüssel erstellt ist. Um sie zu ändern, widerrufen Sie den Schlüssel und erstellen einen neuen. Ein Raum, den der Schlüssel anlegt, kommt auf seine Liste.
  • Ihre aktuelle Rolle entscheidet, bei jeder Anfrage. Wo Sie Betrachter sind, liest selbst ein write-Schlüssel nur; sobald Sie einen Raum verlassen, verliert der Schlüssel ihn bei seiner nächsten Anfrage.
  • Öffentliche Räume, in denen Sie nicht Mitglied sind, bleiben dem Schlüssel verschlossen, obwohl jeder sie im Browser öffnen kann.
  • Ein Widerruf oder der Ablauf eines Schlüssels wirkt ab der nächsten Anfrage.
Berechtigung Erlaubt dem Schlüssel…
read Ihre Räume auflisten, ihre Daten lesen und exportieren
write Daten hinzufügen und ändern, Räume erstellen
upload Ebenendateien hochladen

In einem Raum darf ein Schlüssel jeden Endpunkt aufrufen, den ein Raum-Token aufrufen darf, mit derselben Berechtigung für jeden.

Route Erfordert Antwortet
GET /api/rooms read Ihre Räume; nur die auf der Liste des Schlüssels, falls er eine hat
GET /api/users/me read { "user": { "userId", "username", "plan" }, "rooms": [...] }, nie Ihre E-Mail-Adresse
GET /api/account/usage read Ihre Speichersummen; die Liste pro Raum enthält nur die Räume des Schlüssels
POST /api/rooms/:roomId write legt den Raum an, angerechnet auf Ihren Tarif; ein bestehender Raum wird nie geändert (403)
Terminal window
export API=https://app.collmap.com
AUTH="Authorization: Bearer cmap_u_…" # Ihr Schlüssel
# Die Räume, die der Schlüssel erreicht
curl -s "$API/api/rooms" -H "$AUTH" | jq '.[].name'
# Einen Raum anlegen: Wählen Sie eine neue ID aus genau 10 Zeichen aus [A-Za-z0-9_-]
curl -s -X POST "$API/api/rooms/aB3dEfGhIj" -H "$AUTH" \
-H "Content-Type: application/json" -d '{"name":"Survey 2026"}' | jq .

Diese Aufrufe antworten mit 403 api_token_not_allowed, unabhängig von den Berechtigungen des Schlüssels:

  • einen Raum löschen, leeren oder umbenennen oder seine Sichtbarkeit oder Einstellungen ändern;
  • Mitglieder einladen oder entfernen;
  • Schlüssel oder Raum-Tokens erstellen, auflisten oder widerrufen;
  • Admin-Routen oder den Echtzeit-WebSocket erreichen.

Was ein Schlüssel schreibt, wird Ihnen zugeordnet, mit dem Namen des Schlüssels daneben: Die App zeigt „Jane · über field-app“ bei Markern, Ebenen, Kommentaren und in der Zeitleiste. Kann Ihr Benutzername nicht angezeigt werden (er ist leer oder enthält ein @), zeigt die App stattdessen „User“ und den Anfang Ihrer Benutzer-ID, wie bei allem, was Sie erstellen: Eine E-Mail-Adresse zeigt sie nie.