Appel de l'API

Tout ce que fait l’application, elle le fait via la même API HTTP que vous pouvez appeler vous-même. Chaque point de terminaison est répertorié dans la référence API REST ; cette page couvre les trois choses dont vous avez besoin avant que l’un d’eux ne fonctionne.

Authentifier

Envoyez un jeton d’identité en tant que credential de porteur :

curl -H "Authorization: Bearer <your-token>" \
     https://app.example.com/api/workflows

Les jetons proviennent de la connexion. Il n’y a pas de clé API distincte à créer : votre identité API est votre identité d’utilisateur, donc tout ce à quoi vous pouvez accéder dans l’application, vous pouvez y accéder avec curl, et rien d’autre.

Chaque point de terminaison nécessite cela. Il n’y a pas de lecture anonyme : une demande sans credential est refusée avant d’atteindre le point de terminaison, quel que soit le point de terminaison. Les quelques chemins réellement publics — la liste de prix, cette documentation — sont publics par décision explicite, pas parce que l’authentification est facultative.

Indiquez quel workspace vous voulez dire

Si vous appartenez à plus d’un workspace, indiquez-nous dans lequel une demande agit :

curl -H "Authorization: Bearer <your-token>" \
     -H "X-Account-Id: <workspace-id>" \
     https://app.example.com/api/workflows

Omettez-le et vous obtiendrez votre workspace le plus ancien. Envoyez-en un dont vous n’êtes pas membre et vous obtiendrez à la place votre workspace le plus ancien — l’en-tête sélectionne parmi les workspaces auxquels vous appartenez déjà, il ne donne pas accès à ceux dont vous ne faites pas partie.

L’en-tête est nommé X-Account-Id pour des raisons historiques ; la valeur est un identifiant de workspace. Partout ailleurs, le mot fait référence à votre propre connexion.

Vous ne verrez jamais que les données de vos propres workspaces. Un point de terminaison de collection renvoie vos lignes et rien d’autre ; demander quelque chose dans un workspace dont vous n’êtes pas membre est refusé plutôt que renvoyé vide.

Quel hôte vous appelez est important

Si votre organisation gère plus d’un produit de marque, le nom d’hôte que vous appelez sélectionne lequel. Le même credential sur deux hôtes différents voit deux ensembles différents de workspaces — ceux que vous avez dans chacun. Cela est délibéré : un workspace appartient à une marque, et une demande doit indiquer pour quelle marque elle est destinée.

Lecture des erreurs

Statut	Signification	Que faire
`401`	Pas de credential, ou il n’est pas valide	Connectez-vous à nouveau et réessayez avec un nouveau jeton
`402`	Le workspace n’a pas d’abonnement actif	Les lectures fonctionnent toujours ; les écritures ont besoin d’un plan. Voir Utilisation et facturation
`403`	Authentifié, mais pas le vôtre à toucher	Vous n’êtes pas membre de ce workspace, ou l’action nécessite le propriétaire
`404`	Non trouvé — ou pas le vôtre	Pour les ressources adressées par nom, nous répondons 404 plutôt que 403 afin que la réponse ne confirme pas que quelque chose existe
`429`	Limité par le taux, ou le crédit prépayé est épuisé	Ralentissez ; s’il dit crédit, rechargez

Un 402 vaut la peine d’être compris : un workspace non payé devient en lecture seule plutôt que d’être désactivé. Vous conservez l’accès à tout ce qui s’y trouve déjà et vous pouvez toujours l’exporter — vous ne pouvez simplement pas créer de nouveau travail tant qu’il n’y a pas de plan à nouveau. Les points de terminaison de facturation et d’adhésion continuent à fonctionner, car c’est ainsi que vous le réparez.

Les webhooks et les intégrations s’authentifient différemment

Deux familles de points de terminaison ne sont pas appelées par une personne connectée, donc elles n’utilisent pas votre jeton :

Déclencheurs de webhook portent leur propre jeton dans l’URL, donc un système externe peut démarrer un workflow sans compte utilisateur.
Points de terminaison d’intégration sont autorisés par le jeton d’intégration et la liste des sites autorisés à l’utiliser — voir Intégrer un widget.

Les deux refusent complètement lorsque le workspace propriétaire n’a pas d’abonnement actif, plutôt que de passer en lecture seule. Un étranger sur le site web de quelqu’un d’autre ne devrait pas voir un problème de facturation.