Clés d'API personnelles
Une clé d’API personnelle (préfixe cmap_u_) permet à un script ou à un connecteur d’assistant IA
d’agir en votre nom dans les salles dont vous êtes membre, sans connexion dans le navigateur et sans
un jeton de salle par salle. Elle peut aussi lister vos salles, lire votre profil et
votre consommation de stockage, et créer une salle.
Jeton de salle (cmap_…) |
Clé personnelle (cmap_u_…) |
|
|---|---|---|
| Créé par | le propriétaire de la salle, pour une salle | vous, pour vous-même |
| Atteint | cette seule salle | toutes les salles dont vous êtes membre, ou seulement celles que vous choisissez |
| Droits dans une salle | les permissions du jeton | les permissions de la clé, jamais plus que votre propre rôle dans la salle |
| Niveau du compte | rien | vos salles, votre profil et votre consommation, créer une salle |
Créer une clé
Section intitulée « Créer une clé »-
Ouvrez le menu utilisateur (en haut à droite) et choisissez Clés d’API.
-
Nommez la clé, cochez ses permissions, choisissez quand elle expire (de 7 à 365 jours, 90 par défaut), puis Toutes mes salles ou Seulement ces salles.
-
Sélectionnez Créer une clé, puis copiez la clé tout de suite — elle n’est affichée qu’une fois.
Avec votre session ou un JWT (voir l’Aperçu), jamais avec une clé ni un jeton de salle :
curl -X POST "$API/api/users/me/api-tokens" \ -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \ -d '{"name":"field-app","permissions":["read","write"],"expiresInDays":90}'# → 201 { "id": "…", "token": "cmap_u_…", "name": "field-app", "permissions": ["read","write"],# "roomIds": null, "expiresAt": "…" }Ajoutez "roomIds": ["<roomId>", …] pour limiter la clé à des salles dont vous êtes membre (100 au
plus). Listez vos clés, sans leurs secrets, avec GET /api/users/me/api-tokens ; révoquez-en une avec
DELETE /api/users/me/api-tokens/<id>.
Les règles
Section intitulée « Les règles »- L’expiration est obligatoire : de 1 à 365 jours, 90 si vous ne la précisez pas.
- Au plus 10 clés actives. Une 11e répond
409 too_many_keys: révoquez-en une d’abord. - La liste de salles est fixée à la création de la clé. Pour la changer, révoquez la clé et créez-en une autre. Une salle créée par la clé rejoint sa liste.
- Votre rôle actuel décide, à chaque requête. Là où vous êtes lecteur, même une clé
writene fait que lire ; dès que vous quittez une salle, la clé la perd à sa requête suivante. - Les salles publiques dont vous n’êtes pas membre restent fermées à la clé, même si tout le monde peut les ouvrir dans le navigateur.
- La révocation d’une clé, ou son expiration, prend effet à la requête suivante.
Permissions
Section intitulée « Permissions »| Permission | Permet à la clé de… |
|---|---|
| read | lister vos salles, lire et exporter leurs données |
| write | ajouter et modifier des données, créer des salles |
| upload | téléverser des fichiers de couche |
Dans une salle, une clé peut appeler tous les points de terminaison qu’un jeton de salle peut appeler, avec la même permission pour chacun.
Routes au niveau du compte
Section intitulée « Routes au niveau du compte »| Route | Exige | Répond |
|---|---|---|
GET /api/rooms |
read |
vos salles ; seulement celles de la liste de la clé si elle en a une |
GET /api/users/me |
read |
{ "user": { "userId", "username", "plan" }, "rooms": [...] }, jamais votre e-mail |
GET /api/account/usage |
read |
vos totaux de stockage ; la liste par salle ne contient que les salles de la clé |
POST /api/rooms/:roomId |
write |
crée la salle, comptée dans votre forfait ; une salle existante n’est jamais modifiée (403) |
export API=https://app.collmap.comAUTH="Authorization: Bearer cmap_u_…" # votre clé
# Les salles que la clé atteintcurl -s "$API/api/rooms" -H "$AUTH" | jq '.[].name'
# Créer une salle : choisissez un nouvel identifiant d'exactement 10 caractères parmi [A-Za-z0-9_-]curl -s -X POST "$API/api/rooms/aB3dEfGhIj" -H "$AUTH" \ -H "Content-Type: application/json" -d '{"name":"Survey 2026"}' | jq .Ce qu’une clé ne peut jamais faire
Section intitulée « Ce qu’une clé ne peut jamais faire »Ces appels répondent 403 api_token_not_allowed, quelles que soient les permissions de la clé :
- supprimer, vider ou renommer une salle, ou changer sa visibilité ou ses réglages ;
- inviter ou retirer des membres ;
- créer, lister ou révoquer des clés ou des jetons de salle ;
- atteindre les routes d’administration ou le WebSocket temps réel.
Attribution
Section intitulée « Attribution »Ce qu’une clé écrit vous est attribué, avec le nom de la clé à côté : l’application affiche
« Jane · via field-app » sur les repères, les couches, les commentaires et dans la chronologie. Si votre
nom d’utilisateur ne peut pas être affiché (il est vide ou contient un @), l’application affiche
« User » suivi du début de votre identifiant, comme pour tout ce que vous créez : elle n’affiche jamais
d’e-mail.