Aller au contenu
Sections de la documentation

Authentification

Chaque requête à une API Safecube est authentifiée par une clé d'API. La clé est envoyée dans un en-tête nommé API_KEY : il n'y a ni session, ni cookie, ni échange de jeton, et la même clé authentifie les API Container Tracking, Webhooks, Shipment Management, Ports Intelligence et Congestion.

Trouver votre clé d'API

La clé d'API Safecube est affichée dans l'application web Safecube, sur la page https://app.safecube.ai/api/credentials. Pour y accéder depuis l'application, ouvrez Developers dans la barre latérale, puis l'onglet API Credentials. Seuls un Admin ou un Owner de l'espace de travail peuvent l'ouvrir. Chaque espace de travail a une seule clé. L'onglet est décrit dans Identifiants d'API.

La page affiche un champ nommé API Key, avec la mention « This key must be kept confidential ». La clé est masquée par défaut :

  • le bouton en forme d'œil à côté du champ affiche la clé ;
  • le bouton de copie copie la clé dans le presse-papiers ;
  • le bouton Rotate API key remplace la clé actuelle par une nouvelle. La clé actuelle est invalidée aussitôt, sans délai de grâce : toute requête encore envoyée avec elle échoue, mettez donc vos applications à jour avec la nouvelle clé. Les webhooks déjà configurés continuent de livrer.

Envoyer la clé d'API

Ajoutez l'en-tête API_KEY à chaque requête, quels que soient l'API et l'endpoint. L'exemple ci-dessous appelle la Container Tracking API avec l'expédition de test gratuite ZZZZ0000000.

curl "https://api.sinay.ai/container-tracking/api/v2/shipment?shipmentNumber=ZZZZ0000000" \
  -H "API_KEY: $SAFECUBE_API_KEY"

L'en-tête se nomme API_KEY, en entier et avec un tiret bas, et la clé est envoyée telle quelle, sans préfixe Bearer.

Une requête dont la clé manque ou est invalide est rejetée avec 401 Unauthorized ou 403 Forbidden, selon l'API. La page de référence de chaque endpoint liste les codes de statut qu'il renvoie.

Accès à chaque API

Une seule clé d'API authentifie toutes les API Safecube, mais certaines API vérifient aussi que la clé a reçu un accès à elles. La Ports Intelligence API exige cet accès explicitement, et la Congestion API exige un accès au produit Congestion. Une clé sans l'accès requis est rejetée sur les endpoints de cette API.

En-têtes

En plus d'API_KEY, quelques en-têtes HTTP standard sont obligatoires sur une requête à une API Safecube. Les clients HTTP, comme curl, un SDK ou une bibliothèque HTTP, les génèrent en général automatiquement.

En-têteQuand il est obligatoireRôle
API_KEYToujoursAuthentifie la requête avec votre clé d'API Safecube
HostToujours (HTTP/1.1 et versions suivantes)Nom d'hôte du serveur qui reçoit la requête : api.sinay.ai
Content-TypeQuand la requête a un corps (POST, PUT, PATCH)Format du corps de la requête : application/json
Content-LengthQuand la requête a un corpsLongueur du corps de la requête, en octets

Une requête avec un corps JSON porte donc ces en-têtes :

POST /webhook/api/v1/endpoint HTTP/1.1
Host: api.sinay.ai
API_KEY: <your API key>
Content-Type: application/json
Content-Length: 411