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 |
Einen Schlüssel erstellen
Abschnitt betitelt „Einen Schlüssel erstellen“-
Öffnen Sie das Benutzermenü (oben rechts) und wählen Sie API-Schlüssel.
-
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.
-
Wählen Sie Schlüssel erstellen und kopieren Sie den Schlüssel sofort — er wird nur einmal angezeigt.
Mit Ihrer Sitzung oder einem JWT (siehe Überblick), nie mit einem Schlüssel oder einem Raum-Token:
curl -X POST "$API/api/users/me/api-tokens" \ -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \ -d '{"name":"field-app","permissions":["read","write"],"expiresInDays":90}'# → 201 { "id": "…", "token": "cmap_u_…", "name": "field-app", "permissions": ["read","write"],# "roomIds": null, "expiresAt": "…" }Fügen Sie "roomIds": ["<roomId>", …] hinzu, um den Schlüssel auf Räume zu beschränken, in denen Sie
Mitglied sind (höchstens 100). Ihre Schlüssel listen Sie ohne deren Geheimnisse mit
GET /api/users/me/api-tokens auf; einen widerrufen Sie mit DELETE /api/users/me/api-tokens/<id>.
Die Regeln
Abschnitt betitelt „Die Regeln“- 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.
Berechtigungen
Abschnitt betitelt „Berechtigungen“| 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.
Routen auf Kontoebene
Abschnitt betitelt „Routen auf Kontoebene“| 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) |
export API=https://app.collmap.comAUTH="Authorization: Bearer cmap_u_…" # Ihr Schlüssel
# Die Räume, die der Schlüssel erreichtcurl -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 .Was ein Schlüssel nie darf
Abschnitt betitelt „Was ein Schlüssel nie darf“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.
Zuordnung
Abschnitt betitelt „Zuordnung“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.