API REST : créer et gérer vos clés
Générez des clés API pour connecter Joinways à vos outils via l'API REST, et gérez leurs permissions et leur révocation en toute sécurité.
Mis à jour le
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 un accès complet à votre espace de travail.
Cet article explique comment créer une clé, ce qu'elle peut atteindre, comment l'utiliser dans vos requêtes, puis la faire tourner ou la révoquer. Il sert aussi de référence pour le périmètre 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, la page Développeurs reste désactivée.
- 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
- Comprendre exactement ce qu'une clé peut atteindre
- 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.
Cas avancé : pour une application tierce qui agit au nom d'un utilisateur (et non avec votre propre clé), Joinways expose aussi un serveur OAuth 2.1 (authorization code + PKCE). Les détails figurent dans la référence API.
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.
- Ouvrez Paramètres puis Développeurs.
- Cliquez sur Nouvelle clé, donnez-lui un nom clair (ex. « Site web ») et une durée d'expiration.
- Posez une expiration si l'intégration est temporaire : c'est votre principal filet de sécurité.
- Copiez la clé affichée immédiatement : elle n'est montrée qu'une seule fois.
- 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.
Ce qu'une clé peut atteindre
C'est le point le plus important à connaître avant de coller une clé quelque part : une clé API Joinways porte un accès complet à l'espace de travail où elle a été créée. Elle peut lire ET écrire toutes les ressources exposées par l'API REST.
Il n'existe pas de clé en lecture seule, ni de réglage de permissions par clé. Une clé créée pour afficher vos disponibilités sur un site peut, techniquement, modifier un devis ou supprimer un événement.
La protection n'est donc pas un périmètre restreint, elle est opérationnelle : une clé par intégration, une expiration quand vous pouvez en poser une, un stockage dans un gestionnaire de secrets, et une révocation immédiate au moindre doute.
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).
- Construisez l'URL de la ressource à partir de l'URL de base /api/v1.
- Ajoutez l'en-tête Authorization avec votre clé en jeton Bearer.
- Envoyez la requête : une clé valide et autorisée renvoie les données, sinon une erreur d'authentification.
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.
- Créez une nouvelle clé en suivant les étapes ci-dessus.
- Déployez la nouvelle clé dans votre intégration.
- Vérifiez que tout fonctionne avec la nouvelle clé.
- Révoquez l'ancienne clé une fois la bascule confirmée.
Pour révoquer immédiatement une clé (par exemple si elle est compromise) :
- Retournez dans Paramètres puis Développeurs.
- Cliquez sur Révoquer à côté de la clé concernée.
- La clé cesse de fonctionner immédiatement.
Référence : périmètre et états d'une clé
Cette section récapitule ce qu'une clé atteint et les états dans lesquels elle peut se trouver.
Périmètre
- Accès complet : une clé lit et écrit toutes les ressources de son espace de travail — événements, devis, entreprises, contacts, catalogue et le reste.
- Pas de droits par clé : Joinways ne propose pas de clé en lecture seule. Traitez chaque clé comme un accès complet.
- Frontière de l'espace : une clé n'atteint jamais les données d'un autre espace de travail. C'est la seule limite qu'elle porte.
É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 sert la requête dans son espace de travail, quelle que soit la ressource.
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.
- Une clé, une intégration : puisqu'on ne peut pas restreindre les droits d'une clé, isoler les usages est ce qui limite la portée d'une fuite.
- 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é sur la page Développeurs ; 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 : l'espace de travail n'est plus au plan Pro, ou la ressource visée ne lui appartient pas.
- Solution : vérifiez le plan de l'espace de travail, puis que la ressource visée lui appartient bien. Les droits d'une clé ne se règlent pas : ils sont toujours un accès complet à son propre espace.
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é nommée « Site web », vous la stockez côté SERVEUR de votre site (jamais dans le JavaScript de la page, où n'importe quel visiteur pourrait la lire), puis vous interrogez l'API pour afficher vos créneaux disponibles. Gardez en tête que cette clé pourrait aussi écrire : si le site est compromis, révoquez-la immédiatement.
Exemple 2 — Synchroniser une automatisation
Vous créez une clé « Zapier », 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 la page Développeurs 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 — mais dans cet espace, elle atteint tout.
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
Prêt à centraliser vos demandes événementielles ?