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://app.collmap.com(En exécution locale, le serveur d’API se trouve à http://localhost:3001.)
Jetons de salle et clés personnelles ne fonctionnent que sur l’application où ils ont été créés :
appelez donc l’API sur app.collmap.com. collmap.com sans app. répond avec une ancienne API qui
n’a pas de clés personnelles.
Trois façons de s’authentifier
Section intitulée « Trois 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 trois 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.
3. Une clé d’API personnelle (cmap_u_…)
Section intitulée « 3. Une clé d’API personnelle (cmap_u_…) »Pour un script ou un connecteur d’assistant IA qui travaille en votre nom dans toutes vos salles, et pas dans une seule. Vous la créez vous-même depuis le menu utilisateur (Clés d’API). Elle atteint les salles dont vous êtes membre, ou seulement celles que vous choisissez, avec au plus vos propres droits dans chacune. Elle peut aussi lister vos salles, lire votre profil et votre consommation, et créer une salle — voir Clés d’API personnelles.
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.
Une clé personnelle est fermée par défaut de la même façon : elle est acceptée sur ces mêmes points de terminaison, dans les salles qu’elle atteint, plus quatre routes au niveau du compte listées sur Clés d’API personnelles, et refusée partout ailleurs.
WebSocket
Section intitulée « WebSocket »La collaboration en temps réel passe par un WebSocket Yjs distinct (wss://app.collmap.com/ws). Ce
WebSocket est réservé aux JWT — les jetons de salle et les clés personnelles n’ont pas de voie
WebSocket ; leurs écritures atteignent le document vivant via les points de terminaison REST et se
propagent de là.