Authentification de l'API et jetons Bearer

Comment fonctionne l'authentification

1. Enregistrez-vous et connectez-vous à votre compte Quote3D.
2. Générez un jeton API (JWT) depuis votre tableau de bord sous l'onglet "Tokens".
3. Incluez le jeton dans vos requêtes API. Authorization: Bearer est pris en charge, et X-API-Token est également accepté :
   Authorization: Bearer YOUR_TOKEN_HERE
4. Le serveur vérifie votre jeton et accorde l'accès s'il est valide et non expiré.

Portées des jetons

La portée d'un jeton détermine les points de terminaison qu'il peut atteindre. Vous la choisissez à la création du jeton et pouvez la consulter sur la page Jetons de votre tableau de bord.

• Accès complet — la valeur par défaut pour un jeton côté serveur. Il atteint tous les points de terminaison autorisés par votre offre.
• Widget — la portée à utiliser pour un jeton intégré à une boutique. Elle se limite aux besoins du widget intégrable et ne peut atteindre ni les webhooks, ni les informations de compte, ni l'analytique, ni l'usage, ni les quotas.

Un appel vers un point de terminaison hors de la portée du jeton est rejeté avec un 403, même si le jeton lui-même est valide. Si une requête échoue en 403 alors que le même jeton fonctionne ailleurs, vérifiez sa portée avant toute chose.

Cycle de vie des jetons

• La valeur d'un jeton n'est affichée qu'une seule fois, à sa création. Elle n'est pas récupérable ensuite — enregistrez-la immédiatement dans votre gestionnaire de secrets. Si vous la perdez, effectuez une rotation du jeton pour obtenir une nouvelle valeur.
• Les jetons peuvent être créés avec une date d'expiration. Un jeton expiré cesse de fonctionner et renvoie 401 ; le tableau de bord affiche la date d'expiration de chaque jeton.
• La rotation d'un jeton émet une nouvelle valeur et invalide immédiatement l'ancienne. Déployez la nouvelle valeur avant d'effectuer la rotation, car les requêtes en cours utilisant l'ancien jeton échouent aussitôt.
• Un jeton peut être restreint à une liste d'adresses IP. Les appels provenant de toute autre adresse sont rejetés avec un 403 — une surprise fréquente après un déménagement de serveur ou un changement de passerelle NAT.
• Votre offre limite le nombre de jetons que vous pouvez détenir. Les offres gratuites autorisent un jeton serveur et un jeton widget.

Quand l'authentification échoue

Une requête rejetée renvoie l'enveloppe d'erreur standard avec success: false et un message court. Basez votre logique sur le code de statut HTTP plutôt que sur le texte du message, qui peut être reformulé.

{
  "success": false,
  "error": "API token has expired"
}

• 401 — le jeton est absent, mal formé, expiré ou révoqué. Vérifiez le nom de l'en-tête et que la valeur n'a pas été tronquée à la copie.
• 403 — le jeton est valide mais non autorisé pour cet appel. Les causes habituelles sont une restriction de portée ou une liste d'IP autorisées qui n'inclut pas l'appelant.

Format du jeton

Les jetons Quote3D sont des identifiants API de type bearer. Les clients doivent les traiter comme des secrets opaques et éviter de dépendre de la structure interne du jeton.

Un JWT se compose de trois parties :

1. En-tête : Spécifie l'algorithme de signature et le type de token.
2. Charge utile (Payload) : Contient les données de l'utilisateur et les revendications (comme l'ID utilisateur, l'adresse e-mail et la date d'expiration).
3. Signature : Vérifie que le token n'a pas été altéré.

Un JWT ressemble à ceci :

Pour les intégrations, la règle importante est simple : stockez le jeton en toute sécurité, envoyez-le avec chaque requête et évitez de l'analyser ou de l'exposer dans le code client, sauf si l'intégration nécessite explicitement un jeton côté client.

Exemple : Utilisation de votre jeton

Voici comment vous pouvez utiliser votre jeton avec curl. Utilisez un style d'en-tête d'authentification de manière cohérente :

Ou dans l'environnement de test de l'API, collez votre jeton dans la fenêtre d'autorisation (icône de cadenas) pour authentifier votre session. Vous pouvez également utiliser X-API-Token dans les intégrations personnalisées si cet en-tête convient mieux.