Authentification

L'API utilise des clés API secrètes. Chaque clé appartient à un seul espace de travail.

Envoyer la cléLien vers cette section#

Placez la clé dans l'en-tête Authorization en tant que jeton porteur :

GET /api/v1/workspace HTTP/1.1
Host: tradecatalog.app
Authorization: Bearer tc_live_Xk2…

curl https://tradecatalog.app/api/v1/workspace \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"

Les clés commencent toujours par tc_live_. Il n'y a pas de clés de test : testez les choses sur un espace de travail avec des données d'exemple, ou lisez avant d'écrire.

Créer une cléLien vers cette section#

Seuls le propriétaire de l'espace de travail ou un administrateur peuvent créer des clés, dans Paramètres → API.

La clé est affichée une seule fois. Nous ne stockons qu'un hachage SHA-256, donc personne chez TradeCatalog ne peut la voir à nouveau. Les paramètres affichent les premiers caractères (comme tc_live_Xk2m…) pour que vous puissiez distinguer les clés.

Un espace de travail peut avoir jusqu'à 20 clés actives. Donnez à chaque système sa propre clé, afin que vous puissiez révoquer l'une sans affecter les autres.

Qui peut avoir des clésLien vers cette section#

L'espace de travail a besoin de l'une de ces options pour créer des clés :

• une souscription active
• un essai Pro
• un compte de pilote (organisé avec Happy Webs)

Les espaces de travail de démonstration ne peuvent pas créer ou utiliser de clés.

Si la souscription expire, vous bénéficiez de 14 jours de grâce. Après cela, l'espace de travail redevient gratuit. Les clés existantes peuvent toujours lire, mais les écritures API échouent avec 403 read_only jusqu'à ce que Pro soit à nouveau actif. Les modifications du catalogue et les commandes des acheteurs dans l'application continuent de fonctionner.

Ce qu'une clé peut faireLien vers cette section#

Une clé agit avec les permissions de la personne qui l'a créée, telles qu'elles sont actuellement. Une clé créée par un propriétaire ou un administrateur peut lire tous les clients, tous les prix des clients, toutes les commandes et le journal d'activité. Traitez-la comme le mot de passe de cette personne. Une clé créée par quelqu'un limité à ses clients ou régions assignés ne voit que ces clients et leurs commandes, prix et activité ; tout autre client ou commande renvoie 404, de la même manière qu'une clé qui n'existe pas, et les changements de prix renvoient 403.

Si cette personne obtient plus tard un rôle plus restreint, la clé s'adapte également : une écriture que le nouveau rôle n'autorise pas échoue avec 403 forbidden, de la même manière qu'avec l'application. Si elle quitte l'espace de travail, la clé ne fonctionne plus avec 401 key_owner_removed. Créez une nouvelle clé à partir de quelqu'un qui a toujours accès.

Dernière utilisation et révocationLien vers cette section#

Les paramètres indiquent quand chaque clé a été utilisée pour la dernière fois (mis à jour toutes les heures au maximum). Choisissez Révoquer pour arrêter immédiatement une clé. La prochaine demande avec celle-ci obtient 401 unauthorized. Les clés révoquées ne peuvent pas être restaurées.

Qui est enregistré pour les modificationsLien vers cette section#

Les écritures apparaissent dans le journal d'activité de l'espace de travail sous le nom de API key “Sage stock sync”. Les changements d'état des commandes sont enregistrés contre la personne qui a créé la clé.

Gardez les clés en sécuritéLien vers cette section#

• Gardez les clés sur votre serveur, dans des variables d'environnement ou un gestionnaire de secrets.
• Ne mettez jamais une clé dans une page web, une extension de navigateur ou une application mobile. L'API ne permet pas les requêtes depuis le navigateur (CORS) pour cette raison.
• Ne commettez jamais une clé dans git. Si vous le faites, révoquez-la et créez-en une nouvelle.
• Utilisez une clé en lecture seule là où vous n'avez besoin que de lire.

ErreursLien vers cette section#

Voir Erreurs pour la liste complète.