Aperçu et authentification
CollMap dispose d’une API HTTP RESTful (bâtie avec Fastify) pour gérer salles, repères, couches, imports, commentaires et exports. Presque tout ce que vous faites dans l’application est possible en HTTP — le cas le plus utile étant de piloter une seule salle depuis un script avec un jeton limité à cette salle.
URL de base
Section intitulée « URL de base »Tous les points de terminaison sont servis depuis l’origine de l’application :
https://collmap.com(En exécution locale, le serveur d’API se trouve à http://localhost:3001.)
Deux façons de s’authentifier
Section intitulée « Deux façons de s’authentifier »Chaque point de terminaison protégé attend un jeton porteur dans l’en-tête Authorization :
Authorization: Bearer <token>Il existe deux types de jetons :
1. Une session utilisateur (JWT)
Section intitulée « 1. Une session utilisateur (JWT) »Pour agir en votre nom — tout ce que votre compte peut faire, y compris les opérations réservées au propriétaire (créer / supprimer / renommer des salles, inviter des membres, émettre des jetons d’API, lire votre compte). Une session de navigateur connectée échange son cookie OIDC contre un JWT de courte durée :
GET /api/auth/token→ { "token": "<jwt>" }. Le JWT est de courte durée et renouvelé automatiquement dans l’application.
2. Un jeton d’API de salle (cmap_…)
Section intitulée « 2. Un jeton d’API de salle (cmap_…) »Pour les scripts et outils externes qui envoient des données dans une salle (ou en extraient), sans session de navigateur. Vous l’émettez une fois en tant que propriétaire de la salle et l’utilisez directement. Les jetons de salle sont limités à une salle et aux opérations sur les données — voir Jetons d’API de salle.
La portée des jetons est fermée par défaut
Section intitulée « La portée des jetons est fermée par défaut »Un jeton de salle n’est accepté que sur les points de terminaison de données, limités à la salle,
qu’il a explicitement le droit d’atteindre. Présentez-le ailleurs et la requête est rejetée avec
403 api_token_not_allowed — c’est voulu. Un jeton utilisé contre une autre salle, ou sans la
permission requise, obtient également un 403. La liste blanche complète figure sur la page
Jetons d’API de salle.
WebSocket
Section intitulée « WebSocket »La collaboration en temps réel passe par un WebSocket Yjs distinct (wss://collmap.com/ws). Ce
WebSocket est réservé aux JWT — les jetons d’API n’ont pas de voie WebSocket ; les écritures par
jeton atteignent le document vivant via les points de terminaison REST et se propagent de là.