Clés et authentification

Clé publique et clé secrète

La clé publique circule dans l’URL sous la forme ?key=. Elle est publique par conception : elle figure dans le code source de votre page et ne fonctionne que depuis les origines qui y sont listées. La clé secrète circule sous la forme Authorization: Bearer <key> et est réservée à votre serveur. Un navigateur ne peut même pas l’envoyer au service : Authorization ne figure pas dans la liste d’autorisation CORS.

Origines autorisées

Chaque clé publique porte une liste d’au plus 20 origines : schéma, hôte et port exactement tels que le navigateur les envoie, par exemple https://shop.example.com. Une requête provenant de toute autre origine est refusée avec 403 origin_not_allowed, requête préliminaire (preflight) comprise, et le service ne répond jamais avec Access-Control-Allow-Origin: *. La liste est un signal, pas une authentification : les vraies défenses sont le prix calculé côté serveur et les limites de débit.

Clés de test

Une boutique active peut créer jusqu’à 3 clés de test (pk_test_…, sk_test_…). Une clé de test calcule les prix sur votre brouillon validé le plus récent, ce qui permet d’essayer une modification avant de la publier. Elle n’est pas facturée, ses commandes n’envoient ni webhook ni e-mail, et elle expire au bout de 30 jours. Test et production ne se mélangent jamais : un devis de test ne se vérifie qu’avec une clé secrète de test, une commande de test n’est visible que d’une clé de test, et une clé de production n’en voit jamais. Une clé de test peut lister http://localhost comme origine.

Le jeton de projet

Les projets enregistrés sont rattachés à un client, pas à un compte. Le premier POST /cfg/v1/projects émet un jeton aléatoire (cfgpt_…) et ne le renvoie qu’une fois ; l’intégration le conserve et l’envoie sous la forme X-Cfg-Project-Token à chaque appel de projet suivant. Le jeton d’un autre client, la clé d’une autre boutique et un identifiant inconnu répondent tous le même 404.

Rotation sans interruption

La rotation se fait dans la console, et chaque type de clé a une période de chevauchement pour que rien ne casse pendant la bascule.

• Clé publique : la nouvelle clé conserve la même liste d’origines ; l’ancienne continue de fonctionner 168 heures par défaut (au plus 720).
• Clé secrète : affichée une seule fois ; l’ancienne clé continue de s’authentifier 24 heures par défaut (au plus 720).
• Clé de signature des devis : la nouvelle clé signe à partir de maintenant ; les devis signés par l’ancienne clé se vérifient toujours et peuvent encore être commandés pendant 31 jours au plus.
• Secret de webhook : pendant une bascule, les deux secrets signent chaque envoi pendant 7 jours, sous forme de deux valeurs v1=, afin que votre récepteur puisse accepter l’une ou l’autre.

Ce qui ne va jamais dans un navigateur

La clé secrète et le secret de webhook (whsec_…). Gardez-les dans l’environnement de votre serveur, jamais dans une page, un dépôt ou un journal. Si l’un d’eux fuite, effectuez sa rotation dans la console.