Sur cette page
Avant de commencer
L'Open API est en version 1. Son URL de base est https://app.e-tailize.eu/public/api/v1,
elle ne parle que JSON, et la liste des endpoints, avec la forme de chaque requête et de
chaque réponse, se trouve dans Swagger à l'adresse
https://app.e-tailize.eu/swagger/index.html.
L'accès comporte deux niveaux. Votre client, l'entreprise ou l'intégration qui nous appelle,
est validé une seule fois par e-tailize et s'identifie avec l'en-tête X-Api-ClientId sur
les endpoints Auth. Une paire de clés appartient à un utilisateur d'un compte e-tailize, et
les endpoints Connections et Products la lisent dans les en-têtes X-Api-Key et
X-Api-Secret, tous deux obligatoires.
Vous créez une clé Open API avec des appels API : il vous faut donc un outil capable d'envoyer des requêtes HTTP et un endroit sûr où conserver un secret.
Étapes
Envoyez
POST /Auth/request-accesssans en-tête d'identification, avec le nom de votre entreprise, votre adresse e-mail de contact, le nom du partenaire et le motif de la demande. La réponse contient votre client id et le statutPending.Conservez ce client id et envoyez cet identifiant dans l'en-tête
X-Api-ClientIdà chaque autre appel Auth.Attendez qu'e-tailize valide votre client. La validation d'un client est une étape de notre côté, et nous vous prévenons.
Envoyez
POST /Auth/generateavec les informations de l'utilisateur auquel la clé appartient. La réponse contient la clé, le secret et la date d'expiration de la clé.Copiez le secret dans votre propre gestionnaire de secrets avant de fermer la réponse.
Vérifiez la paire avec
POST /Auth/validate/{apiKey}: la clé va dans le chemin, le secret dans le corps de la requête et non dans un en-tête.Envoyez
X-Api-KeyetX-Api-Secretà chaque appel Connections et Products, avecAccept: */*.
Ce qui se passe ensuite
La paire porte le compte et le projet de l'utilisateur pour lequel elle a été générée : vos appels lisent et écrivent donc les données que cet utilisateur voit dans l'application.
POST /Auth/generate vous renvoie la clé que vous avez déjà, sans
secret dans le corps : pour renouveler la clé, vous révoquez d'abord et générez ensuite.
POST /Auth/revoke/{apiKey} supprime la paire, POST /Auth/generate vous en donne une
nouvelle. Gardez la date d'expiration de la réponse à generate et renouvelez la clé avant
cette date.
Vous développez pour l'un de nos clients ? POST /Auth/generate/by-project-and-tenant
rattache la clé à un projet d'un compte client, au lieu du vôtre.
Problèmes fréquents
Un 400 là où vous attendiez un 401. Un en-tête d'identification manquant ou mal formé
renvoie 400 : vérifiez donc que X-Api-Key et X-Api-Secret figurent tous les deux dans la
requête.
Un 401 signifie que les en-têtes sont arrivés dans la bonne forme mais n'ont pas été acceptés : le client n'est pas validé, la clé ou le secret est erroné, la clé a expiré, ou le propriétaire de la clé n'est pas validé.
Un 406 au lieu d'une erreur lisible. Les erreurs sont renvoyées en
application/problem+json, donc un client qui demande Accept: application/json ne voit
jamais le vrai message. Envoyez plutôt Accept: */*.
POST /Auth/validate/{apiKey} qui répond 400 avec "Invalid or unapproved api key and secret"
couvre quatre cas à la fois : clé inconnue, secret erroné, clé expirée, ou utilisateur non
validé.
Une demande d'accès refusée à cause de l'adresse e-mail. Une adresse de contact appartient à un seul client, et une demande validée ou rejetée ne peut pas être envoyée de nouveau.
Questions fréquentes
Où trouver ma clé dans l'application ?
Vous gérez les clés Open API avec des appels API, pas dans un écran : une clé existe dans la
réponse à POST /Auth/generate et dans le gestionnaire où vous l'avez rangée. Les
utilisateurs et leurs rôles sont un autre sujet, voir
Ajouter des utilisateurs et gérer leurs rôles.
Un utilisateur peut avoir deux clés en même temps ?
Non. Un utilisateur a une seule clé active à la fois : POST /Auth/generate refuse donc une
deuxième clé active et répond 200 avec la clé que vous avez déjà, sans secret dans le corps.
C'est pourquoi le renouvellement passe d'abord par POST /Auth/revoke/{apiKey}, puis par
generate.
À quoi ressemble le corps d'une erreur ?
Chaque erreur contient les trois mêmes champs : title, status et errors. errors
contient les noms des champs en erreur, en camelCase, ou la clé general quand le problème
ne concerne pas un champ précis. Il n'y a ni detail, ni instance, ni traceId à lire.
Articles liés
Cet article vous a aidé ?