API REST : créer et gérer vos clés

Votre site affiche vos disponibilités, votre comptable veut les devis signés, un script doit créer les demandes d'un formulaire maison. Dans tous ces cas, un outil doit parler à Joinways sans passer par l'écran.

L'API REST de Joinways sert à cela. Chaque requête se présente avec une clé API, créée dans « Réglages » > « Développeurs ». La clé agit dans votre espace de travail avec les droits du rôle de la personne qui l'a créée.

Ce que vous allez apprendre

• Créer une clé et choisir son expiration.
• Envoyer une première requête à l'API.
• Connaître ce que l'API couvre et ses limites de débit.
• Faire tourner, renommer et révoquer une clé.

Prérequis

• Le rôle « Propriétaire » ou « Administrateur » : eux seuls voient la page « Développeurs ».
• L'offre Pro ou la période d'essai. Sur les autres offres, la page « Développeurs » propose de passer au Pro, et un appel à l'API est refusé.
• Un endroit sûr où ranger la clé : un gestionnaire de secrets, ou les variables d'environnement côté serveur de votre outil.

Astuce : pour relier un assistant IA (Claude, ChatGPT, Cursor), vous n'avez pas besoin de clé. Collez l'URL du serveur MCP et approuvez la connexion : voir Connecter Joinways à Claude (MCP).

1. Créer une clé

1. Ouvrez « Réglages » > « Développeurs ». L'onglet « Clés API » s'ouvre par défaut.
2. Cliquez sur « Nouvelle clé ».
3. Dans « Nom de la clé », indiquez l'usage, par exemple « Site web » ou « Compta ».
4. Dans « Expiration », choisissez « N'expire jamais », « 30 jours », « 90 jours » ou « 1 an ».
5. Cliquez sur « Créer la clé ».

La clé s'affiche sous « Votre clé API (copiez-la maintenant) : ». Copiez-la tout de suite : Joinways ne garde que son empreinte et ne pourra plus jamais la montrer.

Important : une clé perdue ne se récupère pas. Révoquez-la et créez-en une nouvelle.

La liste « Vos clés API » montre pour chaque clé son nom, son préfixe (jw_ suivi de 8 caractères), sa date de création, sa dernière utilisation et son expiration. Une clé expirée porte le badge « Expirée ». En bas de la carte, « URL de base de l'API » rappelle l'adresse à appeler.

Un espace compte au plus 10 clés actives. Au-delà, le message « Limite de 10 clés atteinte. Révoquez-en une pour en créer une nouvelle. » s'affiche.

2. Envoyer une première requête

Toutes les adresses commencent par https://joinways.app/api/v1. Ajoutez la clé dans l'en-tête Authorization, sous la forme Bearer jw_… :

curl https://joinways.app/api/v1/events -H "Authorization: Bearer jw_votre_cle"

L'API répond en JSON. Les listes sont paginées avec page et per_page (50 par défaut, 500 au plus). La référence complète, avec chaque route, ses champs et des exemples, est sur joinways.app/docs/api, aussi accessible par le lien « Documentation de l'API » en haut de la page « Développeurs ». La spécification OpenAPI se télécharge sur joinways.app/openapi.yaml.

3. Ce que l'API couvre

• Événements : liste, fiche, création, modification, statut et étape, archivage et restauration, journées, créneaux d'espace, staff, contacts, notes, tâches, fichiers, emails, fiche de fonction et son PDF, import d'un devis signé.
• Horaires par jour : un événement sur plusieurs jours peut avoir des horaires différents chaque jour, via le champ day_hours. Il vaut null quand tous les jours ont les mêmes horaires.
• Demandes : liste, fiche, création, statut, espaces demandés, conversion en événement, rattachement à un événement existant, fusion de deux demandes.
• Devis : liste, détail avec ses lignes, création, duplication, annulation, PDF, statut, lignes ajoutées, modifiées ou réordonnées. Un devis venu d'une plateforme renvoie aussi les lignes lues sur son PDF (document_lines), en lecture seule.
• Catalogue et forfaits : les articles du catalogue, et les forfaits composés créés ou modifiés par leur composition (is_package, components). Sur un devis, un forfait s'ajoute en une seule ligne.
• Entreprises, personnes et tâches, avec les notes d'entreprise et la recherche.
• Lieux : espaces, heures d'ouverture, fermetures, jours fériés, disponibilités et conflits sur une période.
• Analyses : vue d'ensemble, demandes, réactivité, indicateurs commerciaux, comptables et d'événements.
• Webhooks, recherche globale, notifications et membres de l'équipe.

Chaque route applique les règles de l'app. Un événement archivé est en lecture seule, un devis signé ne se modifie plus, et un rôle sans accès aux demandes ou aux devis reçoit une erreur 403 sur ces routes.

4. Ce qu'une clé peut faire

Une clé porte les droits de lecture et d'écriture du rôle de son auteur, tels qu'ils sont aujourd'hui. Si un administrateur repasse membre, ses clés perdent aussitôt les droits correspondants. S'il quitte l'espace, ses clés cessent de fonctionner.

Il n'existe pas de clé en lecture seule. Une clé créée pour afficher des disponibilités peut, techniquement, modifier un devis. La protection est donc opérationnelle : une clé par outil, une expiration quand c'est possible, et une révocation au moindre doute.

5. Limites de débit et reprises

• Offre Pro : 600 requêtes par minute et 100 000 par jour pour l'espace.
• Période d'essai : 200 requêtes par minute et 5 000 par jour.
• Par adresse IP : 300 requêtes par minute, avant même l'authentification.
• Envoi d'emails : 20 par minute pour l'espace.

Chaque réponse porte les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Au-delà d'une limite, l'API répond 429 avec un en-tête Retry-After en secondes.

Pour rejouer une écriture sans risque de doublon, après une coupure réseau par exemple, envoyez un en-tête Idempotency-Key avec une valeur unique. Pendant 24 heures, la même requête avec la même valeur renvoie la réponse de la première, sans refaire l'action.

6. Faire tourner, renommer ou révoquer une clé

Pour remplacer une clé sans coupure :

1. Créez une nouvelle clé.
2. Déployez-la dans votre outil et vérifiez qu'il fonctionne.
3. Révoquez l'ancienne.

Pour révoquer une clé, cliquez sur l'icône corbeille à côté d'elle. La fenêtre « Révoquer la clé « Site web » ? » rappelle que les intégrations qui l'utilisent cessent de fonctionner tout de suite. Confirmez avec « Révoquer la clé ». La clé disparaît de la liste.

L'icône crayon renomme une clé sans changer sa valeur. Chaque création, renommage et révocation est consigné dans un journal d'audit.

Exemple : les disponibilités d'un domaine sur son site

Un domaine de réception veut afficher ses dates libres sur son site. Il crée une clé « Site web » avec une expiration d'un an et la range côté serveur, jamais dans le JavaScript de la page. Son site appelle GET /api/v1/venues/{venueId}/conflicts sur les trois prochains mois : la réponse liste les événements qui occupent déjà le lieu, en tenant compte des espaces combinés, des temps de montage et de démontage, des fermetures et des jours sans ouverture. Le site grise ces dates. Dans un an, l'équipe crée une nouvelle clé avant d'avoir à révoquer l'ancienne.

Dépannage

L'API répond 401

Cause : la clé est absente, mal copiée, expirée ou révoquée, ou son auteur a quitté l'espace. Solution : vérifiez l'en-tête Authorization: Bearer jw_…, puis l'état de la clé dans « Développeurs ». Au besoin, créez une nouvelle clé depuis un compte actif.

L'API répond 403

Cause : l'espace n'a plus l'offre Pro ni l'essai (plan_not_eligible), ou le rôle de l'auteur de la clé n'autorise pas l'action. Un rôle « Opérations » ne lit ni les demandes ni les devis, un rôle « Lecture seule » n'écrit rien. Solution : vérifiez l'offre et le rôle dans « Réglages » > « Coéquipiers », ou créez la clé depuis un compte propriétaire ou administrateur.

L'API répond 404 sur un identifiant qui existe

Cause : l'élément appartient à un autre espace, ou à un lieu que l'auteur de la clé ne voit pas. Solution : vérifiez l'identifiant et les lieux attribués à ce coéquipier.

L'API répond 409

Cause : l'état de l'enregistrement refuse l'action, par exemple un événement archivé ou un devis signé. Le champ error.details.reason précise la raison (event_archived, quote_locked…). Solution : lisez cette raison, par exemple restaurez l'événement avec POST /api/v1/events/{id}/unarchive avant de le modifier.

L'API répond 429

Cause : une limite de débit est atteinte. Solution : attendez la durée indiquée par Retry-After, puis espacez ou regroupez vos appels.

Questions fréquentes

Puis-je créer une clé en lecture seule ?

Non. Une clé porte les droits du rôle de son auteur. Pour limiter la portée d'une fuite, créez une clé par outil et révoquez-la dès qu'elle ne sert plus.

L'application mobile utilise-t-elle cette API ?

Non. L'application mobile passe par une interface interne, réservée à l'app et non documentée. Seule l'API /api/v1 est publique, stable et décrite dans la référence.

Une clé donne-t-elle accès à d'autres espaces ?

Non. Une clé n'agit que dans l'espace où elle a été créée. Un identifiant d'un autre espace répond 404.

Que devient une clé quand son auteur quitte l'espace ?

Elle cesse de fonctionner. Créez les clés des intégrations durables depuis un compte qui restera.

Voir aussi

• Connecter Joinways à Claude (MCP)
• Les webhooks : pousser vos événements Joinways vers vos outils
• Connecter Joinways à Zapier
• Sécurité et accès