Créer et gérer vos clés API

Les clés API permettent à vos outils (site web, formulaire de demande, logiciel comptable, automatisations externes) de communiquer avec Joinways en toute sécurité, via l'API REST. Chaque clé est un identifiant secret qui authentifie vos requêtes et agit avec les droits que vous lui accordez.

Cet article explique comment créer une clé, la cadrer aux bonnes permissions, l'utiliser dans vos requêtes, puis la faire tourner ou la révoquer. Il sert aussi de référence pour les permissions et les états d'une clé.

Prérequis

Avant de créer une clé, assurez-vous de réunir les conditions suivantes :

• Un accès administrateur : seuls les administrateurs de l'espace peuvent créer, lister et révoquer des clés API.
• Un plan Pro : les clés API sont réservées au plan Pro ; sur les autres plans, l'onglet API reste désactivé.
• Des personnes de confiance : une clé donne accès à vos données, limitez sa création et sa diffusion aux personnes qui en ont réellement besoin.

Ce que vous allez apprendre

• Créer une nouvelle clé API depuis vos paramètres
• Cadrer une clé aux bonnes permissions
• Utiliser la clé dans vos requêtes HTTP
• Faire tourner (rotation) une clé sans interruption
• Révoquer une clé compromise immédiatement

Deux façons de connecter Joinways

Selon votre outil, deux chemins existent pour vous connecter à Joinways. Choisissez celui qui correspond à votre cas.

• Connexion en un clic (MCP) : collez l'URL du serveur MCP dans votre assistant IA et approuvez la connexion — aucun jeton à copier ni gérer. C'est la voie recommandée pour les assistants compatibles.
• Clé API (REST) : pour vos scripts, CLIs et intégrations sur mesure, via l'API REST (URL de base /api/v1). C'est le sujet de cet article.

Si votre outil n'est pas un assistant IA compatible MCP, c'est la clé API REST qu'il vous faut. La suite décrit pas à pas sa création et son usage.

Créer une clé

La création d'une clé prend moins d'une minute. La clé n'est affichée qu'une seule fois, à la création : copiez-la avant de quitter l'écran.

1. Ouvrez Paramètres puis Intégrations, onglet API.
2. Cliquez sur Nouvelle clé, donnez-lui un nom clair (ex. « Site web ») et une durée d'expiration.
3. Vérifiez les permissions accordées avant de valider (voir la section dédiée plus bas).
4. Copiez la clé affichée immédiatement : elle n'est montrée qu'une seule fois.
5. Stockez-la dans un gestionnaire de secrets, jamais en clair dans votre code.

⚠️ Important : une clé perdue ne peut pas être réaffichée. Révoquez-la et créez-en une nouvelle.

Cadrer la clé (permissions)

Avant de valider la création, regardez ce que la clé pourra faire. Une clé hérite des droits que vous lui accordez : plus ils sont larges, plus une fuite est risquée.

Donnez à chaque clé le minimum de droits nécessaires à son usage. Une clé destinée à afficher vos disponibilités sur un site n'a, par exemple, pas besoin de pouvoir modifier des devis.

On distingue généralement les droits de lecture (consulter des données) et d'écriture (créer ou modifier des données). Réservez l'écriture aux intégrations qui en ont vraiment besoin.

Utiliser la clé

Une fois la clé en main, présentez-la à chaque requête envoyée à l'API Joinways. Sans clé valide, la requête est refusée.

Ajoutez la clé dans l'en-tête Authorization de vos requêtes HTTP, sous forme de jeton Bearer : Authorization: Bearer <votre-clé>

Toutes les requêtes ciblent l'URL de base /api/v1, suivie du chemin de la ressource (par exemple les événements ou les devis).

1. Construisez l'URL de la ressource à partir de l'URL de base /api/v1.
2. Ajoutez l'en-tête Authorization avec votre clé en jeton Bearer.
3. Envoyez la requête : une clé valide et autorisée renvoie les données, sinon une erreur d'authentification.

• Consulter la référence API complète (endpoints, schémas)

Faire tourner ou révoquer une clé

Faire tourner une clé, c'est la remplacer par une nouvelle sans interrompre le service. À planifier régulièrement, ou dès qu'un doute apparaît.

1. Créez une nouvelle clé en suivant les étapes ci-dessus.
2. Déployez la nouvelle clé dans votre intégration.
3. Vérifiez que tout fonctionne avec la nouvelle clé.
4. Révoquez l'ancienne clé une fois la bascule confirmée.

Pour révoquer immédiatement une clé (par exemple si elle est compromise) :

1. Retournez dans Paramètres puis Intégrations, onglet API.
2. Cliquez sur Révoquer à côté de la clé concernée.
3. La clé cesse de fonctionner immédiatement.

Référence : permissions et états d'une clé

Cette section récapitule les permissions qu'une clé peut porter et les états dans lesquels elle peut se trouver.

Permissions

• Lecture : autorise la consultation des données (par exemple lister des événements ou des devis) sans pouvoir les modifier.
• Écriture : autorise la création et la modification de données ; à réserver aux intégrations qui en ont besoin.
• Périmètre : une clé n'agit que dans votre espace de travail et selon les droits qui lui ont été accordés à la création.

États d'une clé

• Active : la clé est valide et acceptée par l'API.
• Expirée : la date d'expiration est passée ; la clé est refusée tant qu'elle n'est pas remplacée.
• Révoquée : la clé a été désactivée manuellement et ne fonctionne plus, de façon définitive.

Comment ça marche

À chaque requête, l'API lit la clé présentée dans l'en-tête Authorization et vérifie qu'elle est active, non expirée et non révoquée.

Si la clé est valide, l'API vérifie ensuite qu'elle dispose des permissions nécessaires à l'action demandée, puis renvoie les données.

Toutes les actions sont rattachées à votre espace de travail : une clé ne donne jamais accès aux données d'un autre espace.

Cas particuliers

• Plusieurs intégrations : créez une clé distincte par intégration plutôt que d'en partager une seule, pour pouvoir en révoquer une sans casser les autres.
• Clé sans expiration : si votre intégration tourne en continu, prévoyez tout de même une rotation régulière pour limiter l'exposition.
• Changement d'équipe : lorsqu'une personne quitte le projet, révoquez les clés qu'elle pouvait connaître et créez-en de nouvelles.

💡 Astuce : nommez vos clés d'après leur usage (« Site web », « Compta », « Zapier ») pour identifier en un coup d'œil laquelle révoquer en cas de problème.

Bonnes pratiques de sécurité

Une clé API est un secret au même titre qu'un mot de passe. Quelques règles simples réduisent fortement les risques.

• Une clé par usage : plus facile à révoquer sans tout casser.
• Jamais en clair : stockez vos clés dans un gestionnaire de secrets, pas dans le code ni dans un dépôt Git.
• Ne partagez jamais une clé : par email ou messagerie ; transmettez-la via un canal sécurisé si nécessaire.
• Donnez le minimum de droits : n'accordez l'écriture qu'aux intégrations qui en ont besoin.
• Expiration et rotation : définissez une expiration et révoquez immédiatement toute clé suspecte.

Dépannage

Voici les problèmes les plus fréquents, leur cause probable et la solution.

La requête renvoie une erreur d'authentification (401)

• Cause : la clé est absente, mal formée, expirée ou révoquée.
• Solution : vérifiez l'en-tête Authorization (jeton Bearer), puis l'état de la clé dans l'onglet API ; si elle est expirée ou révoquée, créez-en une nouvelle.

La requête est refusée (403) alors que la clé est valide

• Cause : la clé n'a pas les permissions requises pour l'action demandée.
• Solution : utilisez une clé disposant des droits nécessaires (par exemple l'écriture pour créer une donnée), ou recréez la clé avec les bonnes permissions.

Impossible de retrouver la valeur d'une clé existante

• Cause : une clé n'est affichée qu'à sa création et n'est jamais stockée en clair.
• Solution : révoquez l'ancienne clé et créez-en une nouvelle, puis mettez à jour votre intégration.

Exemples

Exemple 1 — Afficher les disponibilités sur un site

Vous créez une clé en lecture seule nommée « Site web », vous la stockez côté serveur de votre site, puis vous interrogez l'API pour afficher vos créneaux disponibles. En cas de fuite, la clé ne permet que de lire, jamais de modifier vos données.

Exemple 2 — Synchroniser une automatisation

Vous créez une clé « Zapier » avec les droits nécessaires, vous la collez dans votre outil d'automatisation, puis vous planifiez une rotation tous les trois mois. Le jour où vous changez d'outil, vous révoquez l'ancienne clé sans impacter vos autres intégrations.

FAQ

Où trouver la documentation de l'API ?

La référence complète (endpoints, schémas, exemples) est disponible sur la référence API Joinways, accessible via le bouton « Voir la documentation » de l'onglet API ou le lien ci-dessous.

Les clés API sont-elles incluses dans tous les plans ?

Non : elles nécessitent le plan Pro.

Combien de clés puis-je créer ?

Vous pouvez créer plusieurs clés, une par usage ou intégration. C'est même recommandé pour pouvoir en révoquer une sans affecter les autres.

Que se passe-t-il si je perds une clé ?

Une clé perdue ne peut pas être réaffichée. Révoquez-la et créez-en une nouvelle, puis mettez à jour votre intégration.

Une clé donne-t-elle accès aux données d'autres espaces ?

Non. Une clé n'agit que dans l'espace de travail où elle a été créée et selon les droits qui lui ont été accordés.

Faut-il faire tourner les clés régulièrement ?

Oui, c'est une bonne pratique. La rotation limite l'exposition d'une clé dans le temps, même sans incident connu.

Qui peut créer ou révoquer des clés ?

Seuls les administrateurs de l'espace de travail, sur un plan Pro, peuvent gérer les clés API.

Voir aussi

• Référence API Joinways
• Connecteur MCP (Claude)
• Sécurité et accès