Authentification

Deux façons de s’authentifier

Chaque requête vers /api/v1/ doit être authentifiée. PIE accepte deux types d’identifiants, et tous deux se résolvent côté serveur vers le même principal rattaché à l’organisation :

• Clés d’API — identifiants machine à machine de longue durée, envoyés dans l’en-tête X-API-Key. Idéales pour les intégrations serveur.
• Jetons JWT (bearer) — jetons de courte durée obtenus lors d’une connexion, envoyés dans l’en-tête Authorization. Idéaux pour les sessions interactives.

Clés d’API

Créez une clé depuis la page Clés d’API de votre portail producteur (PIP) ou acheteur (PIC). Le secret est affiché une seule fois à la création — conservez-le en lieu sûr ; PIE ne garde qu’un hachage SHA-256 et ne pourra plus jamais l’afficher. Envoyez-le à chaque requête :

curl https://api.example.com/api/v1/products \
  -H "X-API-Key: pie_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Les clés portent des scopes (par exemple products:read, products:write) qui accordent un accès en lecture/écriture grossier, et peuvent être marquées sandbox (lecture seule — voir ci-dessous). Faites une rotation d’une clé pour en générer une remplaçante pendant que l’ancienne continue de fonctionner durant une courte période de grâce, puis révoquez-la pour l’invalider immédiatement.

Clés sandbox

Une clé sandbox lit les données réelles de votre organisation mais rejette toute requête modifiante avec 403 SANDBOX_READONLY. Chaque réponse à une clé sandbox porte l’en-tête X-PIE-Sandbox: true. Utilisez-en une pour explorer l’API — y compris le testeur Try it de la référence d’API — sans aucun risque de modifier les données de production.

Jetons JWT (bearer)

Échangez des identifiants à POST /api/v1/auth/login contre un jeton d’accès de courte durée, puis envoyez-le comme jeton bearer :

curl https://api.example.com/api/v1/products \
  -H "Authorization: Bearer eyJhbGciOi..."

Les jetons d’accès expirent rapidement ; utilisez POST /api/v1/auth/refresh pour en obtenir un nouveau à partir du cookie de rafraîchissement. Contrairement aux clés d’API, les principals bearer ne sont pas limités par des scopes — leur accès est entièrement régi par le rôle de l’utilisateur connecté.