Créer une clé API

Une clé API permet à un autre logiciel — ton ERP, ta GED, un script maison — de lire tes projets ArchiCollab — et, si tu l'autorises, d'y répondre — sans que tu aies à lui confier ton mot de passe.

Créer ta clé

1. Va dans Réglages → Intégrations
2. Dans le bloc Clés API, clique sur Créer une clé
3. Donne-lui un nom qui décrit son usage — « connecteur ERP », « export mensuel ». Ce nom te servira à savoir laquelle révoquer le jour où tu en auras plusieurs
4. Choisis une durée de vie. 90 jours convient à la plupart des usages ; « Jamais » est pratique mais t'oblige à surveiller la clé toi-même
5. Décide si la clé peut écrire : la case « Autoriser l'écriture » est décochée par défaut (voir plus bas). Une seconde case, « Autoriser la publication au client », reste grisée tant que l'écriture n'est pas cochée
6. Clique sur Créer

Ce que la clé peut faire

Exactement ce que tu peux faire, ni plus ni moins. Elle voit les projets auxquels tu as accès, avec les mêmes droits. Si tu n'es pas sur un projet, ta clé ne le voit pas.

Par défaut, elle est en lecture seule : elle ne peut rien créer ni modifier. C'est volontaire — un logiciel tiers ne doit pas pouvoir toucher à tes projets sans que tu l'aies décidé.

Voir une page et télécharger le PDF

Deux routes, en lecture, rendent directement le fichier (jamais une adresse de stockage) :

• GET https://collab.archi/api/v1/versions/:versionId/pages/:pageNumber/image — l'image d'une page de plan (JPEG, 1568 px au plus, 1,5 Mo au plus). Limitée à 30 images par minute. Si la page n'est pas encore rendue, la réponse est 409 : réessaie un peu plus tard.
• GET https://collab.archi/api/v1/documents/:documentId/export?format=with-annotations (ou without-annotations, plus &versionId= pour une version précise) — le PDF du document. Il demande le droit de télécharger : ta clé l'a si tu l'as ; un invité ne l'a pas et reçoit 403. Dans ce PDF, les pièces jointes des annotations apparaissent en vignettes, sans lien : un PDF obtenu par une clé ne contient aucune adresse de stockage.

Deux autres routes rendent des liens de téléchargement valables 5 minutes (jamais une adresse de stockage) :

• GET https://collab.archi/api/v1/versions/:versionId/original-files — le ou les fichiers d'origine déposés pour une version. Même droit que le PDF : un invité reçoit 403.
• GET https://collab.archi/api/v1/annotations/:annotationId/attachments — les pièces jointes du fil d'une annotation (?messageId= pour un seul message).

Chaque annotation renvoyée par l'API porte aussi un champ url : le lien direct pour l'ouvrir dans l'application.

Ces routes sont en lecture : elles ne demandent pas l'option d'écriture. Le détail des codes d'erreur est dans la référence API (docs/api/README.md, section « Fichiers »).

Autoriser l'écriture (option)

À la création, tu peux cocher « Autoriser l'écriture ». La clé peut alors, et seulement :

• répondre à une annotation (avec des @mentions si besoin) ;
• changer le statut d'une annotation (agence uniquement) ;
• créer une annotation sur une version finalisée ;
• déposer un fichier (PDF ou image) : réserver l'envoi, envoyer le fichier, le faire vérifier — 30 dépôts par heure et 500 Mo par 24 heures. Un dépôt ne prévient personne.

Elle ne supprime rien et ne modifie aucun message existant. Elle garde exactement tes droits : un client ne change pas un statut, même avec une clé qui écrit.

Autoriser la publication au client (option)

Une clé qui écrit dépose des versions en brouillon : ton client ne les voit pas tant que quelqu'un ne les a pas validées dans l'application. Pour qu'elle puisse aussi les valider et les envoyer au client (PATCH /api/v1/versions/:id), coche « Autoriser la publication au client (finaliser une version) » à la création — la case n'est active que si l'écriture est cochée.

Sans cette option, une demande de publication est refusée (403 publish_not_authorized) et rien ne part : finalise dans l'application, ou crée une clé avec la publication autorisée.

Ce que ta clé écrit est marqué avec son nom (« via ERP compta ») dans l'application, le portail et l'export PDF. Ton développeur trouvera le détail (en-tête Idempotency-Key obligatoire, limite de 20 écritures par minute, erreurs) dans la référence de l'API.

Ce qui se passe si tu quittes l'agence

Ta clé cesse de fonctionner immédiatement, à la seconde où ton appartenance est retirée. Personne n'a besoin de penser à la révoquer : ton accès est revérifié à chaque appel.

C'est aussi vrai si ton rôle change : la clé suit tes droits du moment, pas ceux que tu avais le jour où tu l'as créée.

Révoquer une clé

Dans le même bloc, clique sur l'icône de corbeille. La clé cesse de fonctionner immédiatement, et tout logiciel qui l'utilisait perd l'accès. Fais-le sans hésiter dès qu'une clé n'est plus utilisée, ou si tu as un doute sur l'endroit où elle a été copiée.

Vérifier ce à quoi une clé donne droit

Ton développeur peut interroger cette adresse pour savoir précisément ce que la clé voit :

GET https://collab.archi/api/v1/me
x-api-key: ta_clé

La réponse liste l'organisation rattachée, le rôle, le nombre de projets accessibles, et canWrite (la clé peut-elle écrire ?).

Si ton intégration cesse de fonctionner

Regarde d'abord le code de réponse. Trois cas, qui n'appellent pas du tout la même réaction :

• 429 — tu vas trop vite. Le plafond est de 120 requêtes par minute et par clé. Ta clé est bonne, tes droits sont intacts : il suffit d'attendre. La réponse porte en général un en-tête Retry-After qui dit combien de secondes. Ne révoque rien, ne recrée rien.
• 403 avec write_not_authorized — la clé est en lecture seule. Crée-en une avec l'écriture autorisée.
• 403 avec publish_not_authorized — la clé écrit mais ne publie pas au client. Crée-en une avec la publication au client autorisée, ou valide la version dans l'application.
• 401 — la clé est refusée. Elle a expiré, elle a été révoquée, ou ton appartenance à l'agence a été retirée. Crée une nouvelle clé, ou vérifie auprès de ton agence que ton compte est toujours actif.

Pour des raisons de sécurité, le 401 ne précise jamais laquelle de ces causes s'applique : le dire renseignerait quelqu'un qui teste des clés au hasard.

Bonnes pratiques

• Une clé par usage. Tu peux en avoir jusqu'à dix. Une clé par logiciel te permet de révoquer l'un sans couper les autres
• Jamais dans un dépôt de code. Une clé copiée dans Git y reste, même après suppression du fichier
• Mets une expiration. Une clé qui expire toute seule est une clé que tu ne peux pas oublier

Voir aussi

• Connecter un assistant IA — l'autre voie, sans clé à copier
• Configurer un webhook — pour être notifié d'un changement, plutôt que d'aller le lire
• Rôles et permissions — ce que chaque rôle peut voir