Authentification
Clés API, clés réelles et clés de test, autorisations, validité, révocation et transmission de la clé lors d'un appel.
L'API INTEGALL fonctionne uniquement avec des clés API. Il n'y a pas de sessions utilisateur ni de cookies.
Obtenir une clé#
Le propriétaire ou un administrateur de l'entreprise de transport crée une clé dans le panneau entreprise, sous ParamètresIntégrations › API et webhooks. La création demande un code récent de son application d'authentification. Voir Clés API et webhooks.
La clé n'est affichée qu'une seule fois. INTEGALL ne conserve ensuite qu'un hachage ; personne ne peut plus lire la clé par la suite.
Types de clés#
| Préfixe | Type | Comportement |
|---|---|---|
rr_live_ | Réelle | Lit et écrit des données réelles. |
rr_test_ | Test | Lit vos données réelles, mais un appel en écriture est seulement vérifié et pas enregistré. Les réponses contiennent "sandbox": true et l'en-tête x-integall-sandbox: true. |
Une clé a la forme rr_live_xxxxxxxx_ suivie de 32 caractères. Les 16 premiers caractères (le préfixe) sont aussi visibles dans le panneau ; ils permettent de reconnaître une clé.
Autorisations (scopes)#
| Autorisation | Dans le panneau | Donne accès à |
|---|---|---|
shipments:read | Lire les envois | GET /v1/shipments, GET /v1/shipments/{ref} |
shipments:write | Demander des transports | POST /v1/shipment-requests |
invoices:read | Lire les factures | GET /v1/invoices |
webhooks:manage | Gérer les webhooks | aucun chemin dans la v1 |
Un appel sans l'autorisation requise reçoit 403 avec le code E_SCOPE.
Transmettre la clé#
Utilisez de préférence l'en-tête Authorization :
curl -H "Authorization: Bearer $INTEGALL_API_KEY" \
"https://api.integall.com/functions/v1/api-v1/v1/invoices"L'en-tête X-API-Key fonctionne aussi :
curl -H "X-API-Key: $INTEGALL_API_KEY" \
"https://api.integall.com/functions/v1/api-v1/v1/invoices"Validité et révocation#
- Une clé est valable jusqu'à sa révocation, ou pendant 30, 90 ou 365 jours (choix lors de la création).
- La révocation prend effet immédiatement, même entre deux appels : INTEGALL vérifie à nouveau la clé à chaque appel.
- Une clé inconnue, révoquée ou expirée reçoit toujours la même réponse :
401avecE_AUTH. INTEGALL n'indique jamais pourquoi une clé n'est pas valide. - Une entreprise a au maximum 20 clés actives.
Remplacer une clé#
- Faites créer une nouvelle clé.
- Installez la nouvelle clé dans votre système.
- Faites révoquer l'ancienne clé.