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

Tutti gli endpoint sono serviti dall’origine dell’app:

https://collmap.com

(Eseguendo lo stack in locale, il server API si trova su http://localhost:3001.)

Due modi di autenticarsi

Ogni endpoint protetto richiede un bearer token nell’intestazione Authorization:

Authorization: Bearer <token>

Esistono due tipi di token:

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.

Anche il cookie di sessione vale come identità

Gli endpoint riservati al proprietario accettano o un JWT bearer o il cookie della sessione autenticata, quindi un fetch(..., { credentials: 'include' }) dal browser funziona senza passare da /api/auth/token. Il JWT esiste per i chiamanti privi di un contenitore di cookie — script, CI, strumenti esterni.

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.

Nota

Un token di stanza agisce come il proprietario che lo ha creato ai fini dell’attribuzione e della quota di spazio, ma non ne riceve mai il ruolo: non può eliminare o rinominare una stanza, invitare membri, emettere token o leggere il tuo account. I dati che scrive vengono attribuiti a api-token:<name>.

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.

WebSocket

La collaborazione in tempo reale passa da un WebSocket Yjs separato (wss://collmap.com/ws). Quel WebSocket è riservato ai JWT — i token API non hanno un percorso WebSocket; le scritture via token raggiungono il documento dal vivo attraverso gli endpoint REST e da lì si propagano.

Dove andare ora

Token API della stanzaEmettere un token, permessi ed elenco completo dei consentiti.

Avvio rapido (cURL)Attraversa una stanza via HTTP con copia e incolla.

RiferimentoOgni endpoint, raggruppato per risorsa.

Errori e limitiCodici di stato, errori di quota e limiti di frequenza.