Jetons d'API de salle

Un jeton d’API de salle (préfixe cmap_) permet à un script ou à un outil d’opérer sur une seule salle sans session de navigateur. C’est la façon recommandée d’automatiser imports, importations de salle, création de repères et exports.

Émettre un jeton

Seul le propriétaire de la salle peut créer des jetons (un jeton ne peut pas en émettre).

Dans l'application

1. Allez dans Mes salles et cliquez sur le bouton API (clé) sur la carte de la salle.

   

2. Choisissez les permissions nécessaires et créez le jeton.

3. Copiez le secret maintenant — il n’est affiché qu’une seule fois.

   

En HTTP

Nécessite votre JWT de propriétaire (voir Aperçu) :

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 est facultatif (1 à 365) ; omettez-le pour un jeton sans expiration.

Listez-les avec GET /api/rooms/$ROOM/api-tokens ; révoquez avec DELETE /api/rooms/$ROOM/api-tokens/<tokenId> (effet immédiat). Ces deux opérations sont réservées au propriétaire, exactement comme l’émission.

Depuis le navigateur

Si vous êtes déjà connecté, l’étape du JWT est inutile — le point de terminaison d’émission accepte aussi votre cookie de session, ce qui fonctionne directement depuis la console des outils de développement sur un onglet 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: "…" }

Pratique pour un jeton ponctuel sans monter de script. C’est le même point de terminaison et la même règle réservée au propriétaire — seule la manière de prouver votre identité diffère.

Attention

Le secret du jeton n’est affiché qu’une fois, à la création. Si vous le perdez, révoquez-le et émettez-en un nouveau.

Permissions

Émettez un jeton avec le strict nécessaire :

Permission	Permet au jeton de…
read	Lire la salle (métadonnées, repères, couches, commentaires, raster) et l’exporter
write	Importer, ajouter des repères (unitaires + en masse), mettre à jour et supprimer des repères, créer des couches, modifier le style d’une couche, les commentaires, l’affichage raster
upload	Importer des fichiers de couche (GeoJSON / zip / gpkg / GeoTIFF)

Astuce

L’erreur la plus courante : un jeton en read seul reçoit un 403 quand il tente d’envoyer des données. Incluez write et/ou upload si vous poussez des données.

Ce qu’un jeton peut appeler

Un jeton n’est accepté que sur ces points de terminaison de données limités à la salle — tout le reste renvoie 403 api_token_not_allowed :

Permission	Points de terminaison
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 en ligne), .../markers (création unitaire), PATCH .../markers/:markerId, DELETE .../markers/:markerId (n’importe quel repère — voir ci-dessous), .../import, .../bulk-import, .../clone-jobs, .../comments[/:id/replies], PATCH .../comments/:id, DELETE .../comments/:id[/replies/:rid] (ses propres commentaires uniquement), 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
(tout jeton)	Suivi des tâches (GET /api/layers/jobs/:id, /api/jobs/:id), tuiles, lecture des entités d’une couche, redirection d’image de repère

`write` autorise un jeton à modifier ou supprimer n'importe quel repère

PATCH et DELETE sur un repère ne se limitent pas aux repères créés par le jeton — un jeton write peut modifier ou supprimer n’importe quel repère de sa salle, y compris ceux ajoutés à la main. (Les commentaires sont plus stricts : un jeton ne peut supprimer que les réponses qu’il a écrites.) N’accordez write que là où c’est acceptable, et préférez un jeton distinct par intégration afin de pouvoir en révoquer un sans perturber les autres.

Ce qu’un jeton ne peut pas faire

Ce sont des opérations de propriétaire ou d’administrateur — effectuez-les en tant que propriétaire (dans l’application, ou avec votre JWT de propriétaire). Elles renvoient volontairement 403 api_token_not_allowed :

• Créer / supprimer / vider / renommer une salle ; basculer en public ; réglages de caméra et de chronologie
• Inviter / retirer des membres ; émettre, lister ou révoquer des jetons
• Lire le compte / la consommation (/api/account), les routes d’administration, register-user, /users/me
• Supprimer une couche ou une couche raster

La salle doit déjà exister (créée par le propriétaire) ; le jeton opère à l’intérieur de celle-ci.

Suite

Rendez-vous au Démarrage rapide pour un parcours complet à copier-coller.