Salta ai contenuti
IT

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
  1. Apri il menu utente (in alto a destra) e scegli Chiavi API.

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

  3. Seleziona Crea chiave, poi copia subito la chiave — viene mostrata una sola volta.

  • 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 write si 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.
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 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)
Terminal window
export API=https://app.collmap.com
AUTH="Authorization: Bearer cmap_u_…" # la tua chiave
# Le stanze che la chiave raggiunge
curl -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 .

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.

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.