Token API della stanza

Un token API della stanza (prefisso cmap_) consente a uno script o a uno strumento di operare su una sola stanza senza sessione di browser. È il modo consigliato per automatizzare caricamenti, importazioni, creazione di segnaposto ed esportazioni.

Emettere un token

Solo il proprietario della stanza può creare token (un token non può emettere token).

Nell'app

1. Vai a Le mie stanze e fai clic sul pulsante API (chiave) sulla scheda della stanza.

   

2. Scegli i permessi che ti servono e crea il token.

3. Copia il segreto adesso — viene mostrato una sola volta.

   

Via HTTP

Richiede il tuo JWT da proprietario (vedi Panoramica):

curl -X POST "$API/api/rooms/$ROOM/api-tokens" \
  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
  -d '{"name":"my-script","permissions":["read","write","upload"],"expiresInDays":30}'
# → { "token": "cmap_…", "id": "…" }   (copy the token — it is not retrievable again)

expiresInDays è facoltativo (1–365); omettilo per un token che non scade mai.

Elencali con GET /api/rooms/$ROOM/api-tokens; revocali con DELETE /api/rooms/$ROOM/api-tokens/<tokenId> (ha effetto immediato). Entrambe le operazioni sono riservate al proprietario, esattamente come l’emissione.

Dal browser

Se hai già effettuato l’accesso, il passaggio del JWT non serve — l’endpoint di emissione accetta anche il tuo cookie di sessione, quindi funziona direttamente dalla console degli strumenti per sviluppatori su una scheda CollMap:

await (await fetch(`/api/rooms/${ROOM}/api-tokens`, {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'my-script', permissions: ['read', 'write', 'upload'] }),
})).json();
// → { token: "cmap_…", id: "…" }

Comodo per un token estemporaneo senza allestire uno script. È lo stesso endpoint e la stessa regola riservata al proprietario — cambia solo il modo in cui dimostri chi sei.

Attenzione

Il segreto del token viene mostrato una volta sola, alla creazione. Se lo perdi, revocalo ed emettine uno nuovo.

Permessi

Emetti un token solo con ciò che gli serve:

Permesso	Consente al token di…
read	Leggere la stanza (metadati, segnaposto, livelli, commenti, raster) ed esportarla
write	Importare, aggiungere segnaposto (singoli + in blocco), aggiornare ed eliminare segnaposto, creare livelli, modificare lo stile dei livelli, i commenti e la resa raster
upload	Caricare file di livello (GeoJSON / zip / gpkg / GeoTIFF)

Consiglio

L’errore più comune: un token con solo read riceve un 403 quando prova a inviare dati. Includi write e/o upload se stai scrivendo dati.

Che cosa può chiamare un token

Un token è accettato solo su questi endpoint dati limitati alla stanza — tutto il resto restituisce 403 api_token_not_allowed:

Permesso	Endpoint
read	GET /api/rooms/:roomId, .../info, .../markers[/:markerId], .../marker-icons, .../comments, .../raster-layers[/:layerId]; GET /api/layers/:roomName; POST .../export, .../export-jobs, GET .../export-size, .../export-jobs/:id[/artifact], .../export-manifest
write	POST .../layers (GeoJSON in linea), .../markers (creazione singola), PATCH .../markers/:markerId, DELETE .../markers/:markerId (qualsiasi segnaposto — vedi sotto), .../import, .../bulk-import, .../clone-jobs, .../comments[/:id/replies], PATCH .../comments/:id, DELETE .../comments/:id[/replies/:rid] (solo i propri commenti), PATCH /api/layers/:layerId, PATCH .../raster-layers/:id/display, POST .../markers/upload-image, POST .../marker-icons
upload	POST /api/layers/upload, .../upload-chunk, .../process-chunked
(qualsiasi token)	Interrogazione delle attività (GET /api/layers/jobs/:id, /api/jobs/:id), tile, lettura degli elementi di un livello, reindirizzamento dell’immagine di un segnaposto

`write` consente a un token di modificare o rimuovere qualsiasi segnaposto

PATCH e DELETE su un segnaposto non si limitano ai segnaposto creati dal token — un token write può modificare o eliminare qualsiasi segnaposto della sua stanza, compresi quelli aggiunti a mano. (I commenti sono più restrittivi: un token può eliminare solo le risposte che ha scritto.) Concedi write solo dove è accettabile, e preferisci un token separato per ogni integrazione, così da poterne revocare uno senza disturbare gli altri.

Che cosa un token non può fare

Sono operazioni da proprietario o amministratore — eseguile come proprietario (nell’app o con il tuo JWT da proprietario). Restituiscono volutamente 403 api_token_not_allowed:

• Creare / eliminare / svuotare / rinominare una stanza; renderla pubblica; impostazioni di camera e cronologia
• Invitare / rimuovere membri; emettere, elencare o revocare token
• Leggere account / consumo (/api/account), rotte di amministrazione, register-user, /users/me
• Eliminare un livello o un livello raster

La stanza deve già esistere (creata dal proprietario); il token opera al suo interno.

Avanti

Vai all’Avvio rapido per una guida completa da copiare e incollare.