Authentification

Chaque appel à l’API de TrakIT indique qui appelle. L’API d’intégration utilise un jeton qu’un utilisateur TrakIT obtient en se connectant. L’API publique utilise des clés d’API, chacune configurée pour un partenaire et quelques points de terminaison.

API d’intégration : jeton de connexion

1. Connectez-vous avec POST /api/v1/Login, avec l’identifiant utilisateur ou l’adresse e-mail et le mot de passe d’un utilisateur qui dispose de l’accès à l’API.
2. En cas de succès, Info contient le jeton.
3. Envoyez le jeton dans un en-tête Token avec chaque autre appel :

GET /api/v1/GetJob?Num=EXBL2610045
Token: your-token

Conservez le jeton et utilisez-le pour chaque appel jusqu’à ce qu’il soit refusé : il n’est pas nécessaire de se connecter pour chaque appel. Chaque connexion ouvre une nouvelle session dans l’historique des connexions de l’utilisateur, et après cinq échecs de connexion en 30 minutes avec le même identifiant utilisateur ou la même adresse e-mail, TrakIT refuse les connexions avec celui-ci pendant 30 minutes.

Ces réponses signifient que le jeton n’a pas été accepté :

Info	Signification
Token missing in header	La requête n’a pas d’en-tête Token.
Invalid Token, Invalid Token Split	L’en-tête contient autre chose qu’un jeton TrakIT, par exemple une valeur tronquée ou modifiée.
Token invalid or expired	Le jeton a expiré, ou sa session a pris fin. Connectez-vous à nouveau.
User account is locked	L’utilisateur a été verrouillé depuis l’émission du jeton.
No such user	L’utilisateur du jeton n’existe plus.
API User must be SysAdmin with API Access	L’utilisateur n’a plus l’accès à l’API.
Your password has expired. Sign in to TrakIT in a web browser to change it.	Le mot de passe de l’utilisateur a expiré.
Database is offline	TrakIT n’est pas disponible pour le moment, par exemple pendant une maintenance. Réessayez plus tard.

Accès à l’API

Seul un administrateur système disposant de l’accès API peut utiliser l’API d’intégration. L’accès à l’API est l’un des modes d’accès de la page Accès des utilisateurs, et seul le support TrakIT peut l’activer ou le désactiver. Sans lui, Login répond User account is not permitted to sign in from the API, et un jeton émis avant sa désactivation est refusé.

Les appels agissent en tant que cet utilisateur. Les dossiers, événements, documents et factures fournisseurs qu’une intégration crée ou modifie sont enregistrés au nom de l’utilisateur, comme si l’utilisateur l’avait fait dans TrakIT. Réservez un utilisateur à chaque intégration et demandez au support TrakIT de lui donner l’accès à l’API : les modifications de l’intégration se distinguent ainsi facilement, et son accès peut être retiré séparément. Un utilisateur distinct évite aussi que l’intégration dérange une personne : une connexion via l’API compte comme la dernière connexion de l’utilisateur ; si le même utilisateur est connecté à TrakIT dans un navigateur web ailleurs, cette session du navigateur est donc déconnectée.

Un utilisateur qui se connecte avec l’authentification à deux facteurs, par un code envoyé par e-mail ou par une application d’authentification, ne peut pas obtenir de jeton : Login ne peut pas recevoir le code ; il refuse donc un tel utilisateur sans lui en envoyer (Two-factor authentication is on for this user, and the API cannot take a code. Use an API user without two-factor authentication.). Utilisez pour l’API un utilisateur sans authentification à deux facteurs.

Les règles de connexion habituelles s’appliquent aussi à Login : un utilisateur verrouillé ne peut pas se connecter, des mots de passe erronés répétés suspendent les connexions de l’utilisateur, et les validations de connexion de votre société, s’il y en a, peuvent la refuser.

Expiration du jeton

Un jeton reste valide tant qu’il est utilisé : il expire après 7 jours sans appel. Une intégration qui appelle l’API au moins une fois par semaine n’a pas besoin de se reconnecter pour cette raison. Un jeton prend aussi fin, avant ce délai, quand :

• l’intégration le déconnecte avec Logout ;
• le mot de passe de l’utilisateur est changé ou réinitialisé, où que ce soit : dans TrakIT, dans l’application TrakIT distincte ou par un administrateur ;
• l’utilisateur est verrouillé, ou déverrouillé.

Quand un appel répond Token invalid or expired, connectez-vous à nouveau avec Login et utilisez le nouveau jeton.

Chaque Login donne un nouveau jeton ; les jetons des connexions précédentes restent valides jusqu’à ce qu’ils prennent fin. Déconnectez avec Logout un jeton que l’intégration n’utilise plus.

Expiration du mot de passe

Si votre société fait expirer les mots de passe (Quand votre mot de passe expire), le mot de passe de l’utilisateur de l’API expire aussi. Dès lors, Login et tous les autres appels répondent Your password has expired. Sign in to TrakIT in a web browser to change it. ; seul Logout fonctionne encore. Pour continuer :

1. Connectez-vous à TrakIT dans un navigateur web en tant qu’utilisateur de l’API, et changez le mot de passe.
2. Reconnectez l’intégration avec Login et le nouveau mot de passe : le changement de mot de passe a mis fin aux autres jetons de l’utilisateur.

API publique : clés d’API

Le support TrakIT configure les clés de l’API publique. Chaque clé n’est autorisée que pour les points de terminaison dont elle a besoin, et le support peut désactiver une clé à tout moment. Une clé incorrecte, désactivée ou non autorisée pour le point de terminaison reçoit Key is disabled, not recognized or permission denied.

Les points de terminaison reçoivent la clé de différentes façons :

Points de terminaison	Envoyer la clé
Factures fournisseurs, GetShipment	Dans un en-tête APIKey : APIKey: your-api-key.
QueryReport, AdvReport	Dans un paramètre APIKey de la chaîne de requête.
GetContainerPosition, ExecuteMove	Dans un en-tête Authorization : Authorization: Bearer your-api-key.
GetList, GetAssetLocation	La propre clé de l’entité, dans un paramètre APIKey de la chaîne de requête.

Une clé fournisseur est aussi liée à un fournisseur, une société et un utilisateur externe : voir Fonctionnement d’une clé fournisseur.

Pour obtenir une clé, adressez-vous au support TrakIT en indiquant les points de terminaison auxquels elle est destinée.

Clés d’API des entités

GetList et GetAssetLocation répondent pour un seul client : l’entité dont la clé est envoyée. Cette clé n’est pas configurée par le support TrakIT : elle est affichée sur la page de l’entité, sous API Key, dès que Enable API Access est activé pour l’entité. Les utilisateurs qui peuvent modifier l’entité l’y voient et la transmettent au client.

La clé est valable pour l’année civile en cours. Elle change au début de chaque année : donnez au client la nouvelle clé depuis la page de l’entité. Si Enable API Access est désactivé pour l’entité, sa clé cesse aussitôt de fonctionner, sur les deux points de terminaison.

Protéger les informations d’identification

• Appelez l’API en HTTPS uniquement.
• Conservez les mots de passe, les jetons et les clés dans le coffre-fort de secrets de votre système, et non dans du code, des scripts ou des documents que d’autres peuvent lire, et ne les envoyez jamais par e-mail.
• Certains points de terminaison reçoivent la clé dans la chaîne de requête : elle fait donc partie de l’adresse. Tenez ces adresses à l’écart des journaux et des captures d’écran que vous partagez.
• Si une clé a pu fuiter, demandez au support TrakIT de la désactiver et d’en émettre une nouvelle. Si un jeton a pu fuiter, déconnectez-le avec Logout. Si le mot de passe de l’utilisateur de l’API a pu fuiter, changez-le, ce qui met aussi fin à tous les jetons de l’utilisateur, et contactez immédiatement le support TrakIT.