Chaque requête à l’API Sway passe en HTTPS par l’URL de base, https://api.business.swayapp.io/v1, et porte une clé API dans son en-tête Authorization. La clé agit au nom de l’utilisateur qui l’a créée : elle atteint les espaces de travail dont cet utilisateur est membre, avec les droits de son rôle dans chacun. Seul GET /health répond sans clé.
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.
- Une clé API. Dans l’application web, choisissez votre nom en bas de la barre latérale, puis Profil, Développeur et Créer une clé API : Développeur et clés API explique chaque champ de la boîte de dialogue.
Envoyer la clé
Gardez la clé dans une variable d’environnement, jamais dans votre code, et envoyez-la comme jeton bearer :
export SWAY_API=https://api.business.swayapp.io/v1
curl "$SWAY_API/workspaces" \
-H "Authorization: Bearer $SWAY_API_KEY"- Une clé commence par
sway_. L’application web l’affiche une seule fois, à sa création : Sway ne conserve qu’une empreinte de la clé, si bien que personne ne peut vous la montrer à nouveau. - L’en-tête prend le mot
Bearer, avec un B majuscule, puis une espace et la clé. - Une clé absente, inconnue, révoquée ou expirée reçoit
401 unauthenticated, avec le même message dans chaque cas.
Quiconque détient la clé agit comme vous
La clé peut faire via l’API ce que ses portées et votre rôle permettent. Si elle fuite, révoquez-la aussitôt dans l’application web, puis créez-en une nouvelle.
Portées
Une portée permet à une clé d’utiliser une ressource de l’API, et s’écrit ressource:verbe :
readcouvre les endpointsGETde la ressource, comme lister ou rechercher les factures.writecouvre toutes les autres méthodes : créer, modifier, supprimer, et des actions comme un export. Elle ne comprend pasread.ressource:*accorde les deux.*:*, Accès complet dans l’application web, accorde chaque ressource, y compris celles que l’API ajoutera plus tard.
Un appel sans la portée dont il a besoin reçoit 403 permission-denied, avec la portée dans son message, comme Missing required scope: invoices:read. La portée décide des endpoints qu’une clé peut appeler ; le rôle de son utilisateur dans chaque espace de travail décide toujours des données qu’elle lit et de ce qu’elle peut modifier.
Chaque portée couvre les pages de la référence de sa ligne :
| Portée | Ressources | Endpoints |
|---|---|---|
workspaces:readworkspaces:write | Workspaces | 3 |
memberships:readmemberships:write | Memberships | 3 |
invitations:readinvitations:write | Invitations | 6 |
consents:readconsents:write | Consents | 7 |
bank-accounts:readbank-accounts:write | Bank accounts | 15 |
currency-exchanges:read | Currency exchanges | 1 |
invoices:readinvoices:write | Invoices | 12 |
counterparties:readcounterparties:write | Counterparties | 6 |
products:readproducts:write | Products | 5 |
payments:write | Payments | 1 |
draft-payments:readdraft-payments:write | Draft payments | 4 |
initiated-payments:readinitiated-payments:write | Initiated payments | 3 |
ledger-entries:readledger-entries:write | Ledger entries | 6 |
chart-of-accounts:readchart-of-accounts:write | Chart of accounts | 11 |
tax-types:readtax-types:write | Tax types | 4 |
account-coding-rules:readaccount-coding-rules:write | Account coding rules | 11 |
workspace-files:readworkspace-files:write | Workspace files | 4 |
users:readusers:write | Users | 3 |
billing-accounts:write | Billing accounts | 1 |
Expiration
Une clé expire 30, 60 ou 90 jours après sa création, à une date que vous choisissez, ou jamais ; l’application web part de 30 jours. Une fois expirée, une clé reçoit 401, comme une clé inconnue : prévoyez son remplacement avant cette date.
Remplacer une clé
Une clé ne se prolonge pas : vous la remplacez par une nouvelle, sans interruption pour votre logiciel.
- Créez la nouvelle clé. Donnez-lui les mêmes portées, et un nom qui la distingue de l’ancienne.
- Passez votre logiciel à la nouvelle clé. Déployez-la, puis vérifiez que ses appels aboutissent.
- Révoquez l’ancienne clé. Dans Profil › Développeur, choisissez Révoquer sur sa ligne. La révocation prend effet aussitôt et est irréversible.
Clés et espaces de travail
- Une clé atteint chaque espace de travail de son utilisateur, avec les droits de son rôle dans chacun. Aucune portée ne peut la limiter à un seul espace de travail.
- Quand l’abonnement d’un espace de travail a pris fin, chaque appel sur ses données répond
409, lectures comprises : voir Erreurs.
Pour permettre à Claude de lire vos espaces de travail avec une clé, voir Connecteur Claude.