L’API Sway permet à votre propre logiciel, comme un script ou un agent, de lire et de modifier les données de vos espaces de travail sans l’application web. Une clé API identifie ce logiciel auprès de Sway et agit en votre nom.
Avant de commencer
- Une licence qui comprend l’API Sway. La licence de base couvre toute la plateforme ; un niveau supérieur ajoute l’API publique. Contactez Sway pour l’ajouter.
- Vos clés sont à vous : une clé atteint les espaces de travail dont vous êtes membre, avec les droits de votre rôle dans chacun, et ne fait donc jamais plus que ce que vous pouvez faire dans l’application web.
Créer une clé API
- Ouvrez la page développeur. En bas de la barre latérale, choisissez votre nom, puis Profil, et Développeur dans le menu du profil.
- Lancez une clé. Choisissez Créer une clé API. Avant votre première clé, la page affiche Aucune clé API avec le même bouton.
- Nommez la clé. Sous Nom, décrivez le logiciel qui l’utilise, comme un serveur de production.
- Réglez l’expiration. Le champ Expire le part de 30 jours. Choisissez une autre durée, Sans expiration ou Date personnalisée.
- Choisissez les portées. Cochez Accès complet, ou les cases Lecture et Écriture de chaque ressource dont le logiciel a besoin.
- Créez-la et copiez le secret. Choisissez Créer la clé. Clé API créée affiche la Clé secrète : copiez-la, conservez-la en lieu sûr, puis choisissez J’ai enregistré ma clé.
Le secret ne s’affiche qu’une fois
Sway ne conserve pas la clé secrète, et l’application web ne l’affiche plus une fois Clé API créée fermée. Toute personne qui la détient peut agir en votre nom via l’API Sway : si vous la perdez, révoquez la clé et créez-en une nouvelle.
Portées
Une portée permet à la clé d’utiliser une partie de l’API. Sans Accès complet, une clé a besoin d’au moins une portée : la boîte de dialogue le signale quand vous n’en cochez aucune.
- Accès complet accorde chaque ressource et chaque action, y compris celles que l’API ajoutera plus tard. Il grise le tableau.
- Le tableau liste les 18 ressources de l’API sous leur nom dans l’API, comme les comptes bancaires, les tiers ou les factures. Lecture permet à la clé de lire une ressource ; Écriture lui permet de créer, de modifier ou de supprimer. Écriture ne comprend pas Lecture : cochez les deux, ou Tout, pour une clé qui fait les deux.
- Les cases de la ligne d’en-tête cochent une colonne entière. Filtrer les ressources restreint le tableau, et la ligne à côté de Portées compte les ressources cochées, comme 3 ressources sur 18.
La page Développeur
Le bloc Documentation de l’API contient une commande qui télécharge la spécification OpenAPI de l’API Sway. Remplacez son paramètre fictif par l’une de vos clés secrètes avant de la lancer. La référence de l’API présente la même spécification, sans clé. Authentification montre comment votre logiciel envoie une clé, et quelle portée chaque endpoint exige.
Pour interroger Claude sur vos espaces de travail, donnez l’une de vos clés au connecteur Claude.
Le tableau Clés API liste vos clés, la plus récente en premier :
- Nom et Portées : les trois premières portées d’une clé s’affichent, et +2 de plus ouvre les autres. Une clé qui a tous les droits affiche Accès complet.
- Créée le et Expire le : le jour de création, et la date d’expiration ou Sans expiration.
- Statut : Active, Expirée ou Révoquée. Une clé qui n’est plus active est grisée et garde sa ligne.
Révoquer une clé
- Trouvez la clé. Dans le tableau Clés API, trouvez la ligne de la clé active.
- Révoquez-la. Choisissez Révoquer au bout de la ligne.
- Confirmez. Révoquer la clé API ? prévient que la révocation interrompt aussitôt toute intégration qui utilise la clé, et qu’elle est irréversible. Choisissez Révoquer la clé.
La clé reste dans le tableau comme Révoquée. Une clé expirée cesse de fonctionner de la même façon : créez une nouvelle clé pour la remplacer.
Champs
La boîte de dialogue Créer une clé API :
| Champ | Ce qu’il attend | Obligatoire |
|---|---|---|
| Nom | Le nom de la clé dans le tableau, de 1 à 100 caractères. | Oui |
| Expire le | 30 jours, 60 jours, 90 jours, Sans expiration ou Date personnalisée, qui ajoute une date à partir de demain. Il part de 30 jours ; une durée compte à partir du moment où vous créez la clé. | Oui |
| Portées | Accès complet, ou au moins une case Lecture ou Écriture dans le tableau des ressources. | Oui |
Étape suivante
Réglez le reste de vos paramètres personnels dans Votre profil.
Réponses liées
Rédigée à partir de l’écran Développeur de l’application web 1.58.0, avec les libellés de ses catalogues EN, FR et DE.