Chiavi API personali
Una chiave API personale (prefisso cmap_u_) permette a uno script o al connettore di un assistente
IA di lavorare a tuo nome nelle stanze di cui sei membro, senza accedere dal browser e senza un
token di stanza per ogni stanza. Può anche elencare le tue stanze, leggere il tuo
profilo e il tuo utilizzo di spazio e creare una stanza.
Token di stanza (cmap_…) |
Chiave personale (cmap_u_…) |
|
|---|---|---|
| Creato da | il proprietario della stanza, per una stanza | te, per te stesso |
| Raggiunge | quella sola stanza | ogni stanza di cui sei membro, o solo le stanze che scegli |
| Diritti in una stanza | i permessi del token | i permessi della chiave, mai più del tuo ruolo in quella stanza |
| Livello account | niente | le tue stanze, il tuo profilo e utilizzo, creare una stanza |
Creare una chiave
Sezione intitolata “Creare una chiave”-
Apri il menu utente (in alto a destra) e scegli Chiavi API.
-
Dai un nome alla chiave, spunta i suoi permessi, scegli quando scade (da 7 a 365 giorni, 90 per impostazione predefinita) e scegli Tutte le mie stanze o Solo queste stanze.
-
Seleziona Crea chiave, poi copia subito la chiave — viene mostrata una sola volta.
Con la tua sessione o un JWT (vedi la Panoramica), mai con una chiave o un token di stanza:
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": "…" }Aggiungi "roomIds": ["<roomId>", …] per limitare la chiave a stanze di cui sei membro (al massimo
100). Elenca le tue chiavi, senza i loro segreti, con GET /api/users/me/api-tokens; revocane una con
DELETE /api/users/me/api-tokens/<id>.
Le regole
Sezione intitolata “Le regole”- La scadenza è obbligatoria: da 1 a 365 giorni, 90 se non la indichi.
- Al massimo 10 chiavi attive. Un’undicesima risponde
409 too_many_keys: revocane prima una. - L’elenco delle stanze è fisso dalla creazione della chiave. Per cambiarlo, revoca la chiave e creane un’altra. Una stanza creata dalla chiave entra nel suo elenco.
- Decide il tuo ruolo attuale, a ogni richiesta. Dove sei Visualizzatore, anche una chiave
writesi limita a leggere; appena lasci una stanza, la chiave la perde alla richiesta successiva. - Le stanze pubbliche di cui non sei membro restano chiuse alla chiave, anche se chiunque può aprirle nel browser.
- La revoca di una chiave, o la sua scadenza, ha effetto dalla richiesta successiva.
Permessi
Sezione intitolata “Permessi”| Permesso | Permette alla chiave di… |
|---|---|
| read | elencare le tue stanze, leggere ed esportare i loro dati |
| write | aggiungere e modificare dati, creare stanze |
| upload | caricare file di livello |
In una stanza, una chiave può chiamare ogni endpoint che può chiamare un token di stanza, con lo stesso permesso per ciascuno.
Route a livello di account
Sezione intitolata “Route a livello di account”| Route | Richiede | Risponde |
|---|---|---|
GET /api/rooms |
read |
le tue stanze; solo quelle nell’elenco della chiave, se ne ha uno |
GET /api/users/me |
read |
{ "user": { "userId", "username", "plan" }, "rooms": [...] }, mai la tua e-mail |
GET /api/account/usage |
read |
i totali del tuo spazio; l’elenco per stanza contiene solo le stanze della chiave |
POST /api/rooms/:roomId |
write |
crea la stanza, conteggiata nel tuo piano; una stanza esistente non viene mai modificata (403) |
export API=https://app.collmap.comAUTH="Authorization: Bearer cmap_u_…" # la tua chiave
# Le stanze che la chiave raggiungecurl -s "$API/api/rooms" -H "$AUTH" | jq '.[].name'
# Creare una stanza: scegli un nuovo id di esattamente 10 caratteri fra [A-Za-z0-9_-]curl -s -X POST "$API/api/rooms/aB3dEfGhIj" -H "$AUTH" \ -H "Content-Type: application/json" -d '{"name":"Survey 2026"}' | jq .Cosa una chiave non può mai fare
Sezione intitolata “Cosa una chiave non può mai fare”Queste chiamate rispondono 403 api_token_not_allowed, qualunque siano i permessi della chiave:
- eliminare, svuotare o rinominare una stanza, o cambiarne la visibilità o le impostazioni;
- invitare o rimuovere membri;
- creare, elencare o revocare chiavi o token di stanza;
- raggiungere le route di amministrazione o il WebSocket in tempo reale.
Attribuzione
Sezione intitolata “Attribuzione”Ciò che una chiave scrive viene attribuito a te, con il nome della chiave accanto: l’app mostra
«Jane · tramite field-app» su segnaposto, livelli, commenti e nella cronologia. Se il tuo nome utente
non può essere mostrato (è vuoto o contiene una @), l’app mostra invece «User» seguito dall’inizio del
tuo id utente, come per tutto ciò che crei: non mostra mai un’e-mail.