Authentification
Jeton bearer
Envoyez Authorization: Bearer sk_live_… à chaque requête. Ne mettez jamais une clé dans une URL ni dans un cookie ; il n’existe pas d’autre en-tête pour cela. Une clé absente, mal formée, révoquée ou expirée reçoit 401 unauthorized, sans indiquer laquelle de ces raisons.
Une clé appartient à un seul espace de travail. GET /v1/workspaces/current le renvoie avec son offre. Si vous envoyez X-Workspace-Id, il doit désigner l’espace de travail de la clé.
Créer des clés
Créez les clés dans l’application sous Settings → API. Les Editors, les admins et le propriétaire créent des clés qui agissent en leur nom ; les admins peuvent aussi renommer et révoquer celles de n’importe qui. Les Viewers ne peuvent pas créer de clés. Un espace de travail peut contenir 50 clés actives.
Le secret n’est affiché qu’une fois et nous n’en conservons que l’empreinte. L’API n’autorise pas les appels de navigateur entre origines : gardez les clés sur votre serveur.
Scopes
Choisissez les scopes à la création de la clé ; ils ne peuvent pas être modifiés ensuite (renouvelez la clé ou créez-en une nouvelle). Une requête a besoin du scope de la route, indiqué à côté de chaque route dans la référence de l’API. Une clé qui ne l’a pas reçoit 403 forbidden avec details.reason missing_scope.
codes:readLister et lire les codes, leurs versions et leur activité ; télécharger des fichiers ; lancer et lire des exports et des séries en masse.Viewer ou supérieurcodes:writeCréer, modifier, mettre en pause, déplacer et supprimer des codes ; création en masse ; envoyer des logos et des fichiers.Editor ou supérieuranalytics:readStatistiques de l’espace de travail et de chaque code, et enregistrements par scan.Viewer ou supérieursubmissions:readRéponses aux formulaires hébergés. Elles contiennent des données personnelles de répondants.Editor ou supérieurfolders:readLister et lire les dossiers.Viewer ou supérieurfolders:writeCréer, renommer, déplacer et supprimer des dossiers. Le partage reste dans l’application.Editor ou supérieurtemplates:readLister et lire les modèles de design.Viewer ou supérieurtemplates:writeCréer, modifier et supprimer des modèles de design.Editor ou supérieurdomains:readLister les domaines personnalisés et leur statut, pour en choisir un pour les nouveaux codes.Viewer ou supérieurwebhooks:readLister les endpoints de webhooks et leurs envois.Admin ou supérieurwebhooks:writeEnregistrer, modifier et supprimer des endpoints de webhooks ; envoyer un événement de test ; renvoyer. Réservé aux admins.Admin ou supérieurtags:readLister les étiquettes de l’espace de travail et le nombre de codes pour chacune.Viewer ou supérieurtags:writeCréer, renommer, recolorer et supprimer des étiquettes. Étiqueter des codes demande Codes · write.Editor ou supérieurcards:readLister et lire les cartes de visite de l’équipe et leurs statistiques.Viewer ou supérieurcards:writeCréer, modifier, désactiver et réattribuer des cartes de visite. Administrateurs uniquement.Admin ou supérieurconversions:writeEnvoyer des conversions depuis votre serveur (commandes, inscriptions) pour l’entonnoir de scans.Editor ou supérieurRôles
Une clé ne fait jamais plus que ce que le rôle actuel de son créateur permet, plafonné à Editor. Si le créateur est rétrogradé à Viewer, la clé perd aussitôt ses scopes d’écriture ; quand le créateur quitte l’espace de travail, ses clés sont révoquées.
webhooks:read et webhooks:write font exception : seuls les admins et le propriétaire peuvent les accorder, et ils ne restent actifs que tant que le créateur est toujours admin.
Restrictions par dossier et par IP
Une clé peut être limitée à 20 dossiers au plus et à leurs sous-dossiers, par exemple une clé par dossier client. Elle ne voit alors rien en dehors, et une écriture ailleurs reçoit 403 avec details.reason api_key_folder_restricted.
Une clé peut aussi être limitée à 20 plages d’IP au plus, en notation CIDR (203.0.113.0/24). Un appel venant d’ailleurs reçoit 403 avec details.reason ip_not_allowed.
Expiration et renouvellement
Une clé peut expirer à une date de votre choix. Renouveler une clé émet un nouveau secret avec les mêmes nom, scopes et restrictions ; l’ancien secret continue de fonctionner 24 heures par défaut (de 0 à 168), pour que vous puissiez déployer le nouveau sans interruption. La révocation prend effet immédiatement.
Ce qu’une clé ne peut pas faire
Les clés n’appellent que les routes de la référence de l’API. Votre compte, les membres et les invitations, la facturation, les paramètres de l’espace de travail, le partage, la configuration des domaines et les clés d’API elles-mêmes restent dans l’application : ces routes répondent à une clé par 403 forbidden et details.reason session_required.