Panoramica e autenticazione
CollMap dispone di un’API HTTP RESTful (costruita con Fastify) per gestire stanze, segnaposto, livelli, caricamenti, commenti ed esportazioni. Quasi tutto ciò che fai nell’app puoi farlo via HTTP — l’uso più utile è pilotare una singola stanza da uno script con un token limitato a quella stanza.
URL di base
Sezione intitolata “URL di base”Tutti gli endpoint sono serviti dall’origine dell’app:
https://app.collmap.com(Eseguendo lo stack in locale, il server API si trova su http://localhost:3001.)
I token di stanza e le chiavi personali funzionano solo nell’app in cui sono stati creati: chiama quindi
l’API su app.collmap.com. collmap.com senza app. risponde con un’API più vecchia, senza chiavi
personali.
Tre modi di autenticarsi
Sezione intitolata “Tre modi di autenticarsi”Ogni endpoint protetto richiede un bearer token nell’intestazione Authorization:
Authorization: Bearer <token>Esistono tre tipi di token:
1. Una sessione utente (JWT)
Sezione intitolata “1. Una sessione utente (JWT)”Per agire a tuo nome — tutto ciò che il tuo account può fare, comprese le operazioni riservate al proprietario (creare / eliminare / rinominare stanze, invitare membri, emettere token API, leggere il tuo account). Una sessione di browser autenticata scambia il proprio cookie OIDC con un JWT di breve durata:
GET /api/auth/token→ { "token": "<jwt>" }. Il JWT ha vita breve e viene rinnovato automaticamente nell’app.
2. Un token API della stanza (cmap_…)
Sezione intitolata “2. Un token API della stanza (cmap_…)”Per script e strumenti esterni che inviano dati in una stanza (o li estraggono), senza sessione di browser. Lo emetti una volta come proprietario della stanza e lo usi direttamente. I token di stanza sono limitati a una stanza e alle operazioni sui dati — vedi Token API della stanza.
3. Una chiave API personale (cmap_u_…)
Sezione intitolata “3. Una chiave API personale (cmap_u_…)”Per uno script o il connettore di un assistente IA che lavora a tuo nome in tutte le tue stanze, non in una sola. La crei tu stesso dal menu utente (Chiavi API). Raggiunge le stanze di cui sei membro, o solo quelle che scegli, con al massimo i tuoi diritti in ciascuna. Può anche elencare le tue stanze, leggere il tuo profilo e il tuo utilizzo e creare una stanza — vedi Chiavi API personali.
La limitazione dei token è fail-closed
Sezione intitolata “La limitazione dei token è fail-closed”Un token di stanza è accettato solo sugli endpoint dati, limitati alla stanza, che gli è
esplicitamente consentito raggiungere. Presentalo altrove e la richiesta viene rifiutata con
403 api_token_not_allowed — per scelta progettuale. Anche un token usato su una stanza diversa, o
privo del permesso richiesto, riceve un 403. L’elenco completo dei permessi è nella pagina
Token API della stanza.
Una chiave personale è fail-closed allo stesso modo: è accettata sugli stessi endpoint, nelle stanze che raggiunge, più quattro route a livello di account elencate in Chiavi API personali, e rifiutata ovunque altrove.
WebSocket
Sezione intitolata “WebSocket”La collaborazione in tempo reale passa da un WebSocket Yjs separato (wss://app.collmap.com/ws). Quel
WebSocket è riservato ai JWT — i token di stanza e le chiavi personali non hanno un percorso
WebSocket; le loro scritture raggiungono il documento dal vivo attraverso gli endpoint REST e da lì si
propagano.