Gérer vos clés API
Une clé API permet à un outil externe (CRM, automatisation Zapier ou Make, script interne, agent IA) de créer, lire, modifier, archiver, réactiver ou supprimer les QR codes de votre compte, de lire leurs statistiques et le quota de créations restant, sans passer par le tableau de bord. Le fonctionnement technique de l'API (adresses, formats, codes d'erreur) est décrit dans la documentation API. Cette fiche explique comment gérer vos clés.
L'accès à l'API est compris dans les plans Pro et Entreprise. Le plan Gratuit ne donne accès ni à l'API ni à aucune clé.
Où gérer vos clés
Les clés se gèrent sur l'écran Clés API, accessible depuis la carte Clés API de l'écran Abonnement (bouton Gérer mes clés API).
- L'écran Clés API est réservé aux membres qui ont la permission Gérant des clés API (ou Administrateur).
- La carte Clés API de l'écran Abonnement n'apparaît qu'aux membres qui ont à la fois Gérant de l'abonnement et Gérant des clés API (ou Administrateur).
| Plan Pro | Plan Entreprise | |
|---|---|---|
| Clés API actives simultanément | 1 | 10 |
| Créations de QR codes via l'API, par mois civil | 5 | 100 |
Créer une clé
- Sur l'écran Clés API, dans le formulaire Créer une clé API, donnez un Nom de la clé qui vous permettra de la reconnaître, par exemple « Intégration Zapier ».
- Dans Droits de la clé, choisissez un préréglage ou Personnalisé (voir ci-dessous).
- Cliquez sur Créer la clé.
- L'écran Copiez votre clé API maintenant affiche la clé complète, qui commence par
qrs_live_. Cliquez sur Copier et enregistrez-la en lieu sûr, par exemple dans le gestionnaire de mots de passe ou de secrets de votre outil. Cochez J'ai copié ma clé en lieu sûr., puis cliquez sur Terminé.
La clé complète ne s'affiche qu'une seule fois. Nous ne la conservons pas en clair et ne pouvons pas vous la renvoyer. Ensuite, l'écran n'affiche plus que ses 4 derniers caractères (
qrs_live_••••abcd). Si vous la perdez, faites-la tourner (voir « Faire tourner une clé ») ou créez-en une nouvelle.
Créer une clé n'est jamais compté dans votre quota mensuel : celui-ci ne s'applique qu'aux QR codes créés via l'API.
Si le nombre maximal de clés de votre plan est atteint, le formulaire de création n'apparaît plus. Attention : pour créer une clé, les clés gelées comptent dans cette limite (voir « Clés gelées »). Révoquez d'abord les clés dont vous n'avez plus besoin.
Utiliser la clé
Votre outil envoie la clé dans l'en-tête de chaque requête : Authorization: Bearer qrs_live_…. La documentation API détaille les opérations disponibles et le droit nécessaire à chacune.
Sur l'écran Clés API, chaque clé indique sa date de création, la date de sa dernière rotation et celle de sa dernière utilisation (ou Jamais utilisée) : pratique pour repérer une clé que plus aucun outil n'utilise. Cette date est mise à jour au plus une fois par minute. Un appel refusé faute de droit ou parce qu'il dépasse la limite de débit ne la modifie pas.
Les dates de l'écran Clés API sont affichées à l'heure suisse. L'API, elle, donne toutes ses dates en UTC, au format ISO 8601 : le Z final signifie UTC. Par exemple, 2026-10-17T22:12:00.000Z correspond au 18 octobre 2026 à 0 h 12 en Suisse. C'est à votre outil de convertir ces dates dans le fuseau horaire voulu.
Choisir les droits d'une clé
Une clé ne peut faire que ce que ses droits autorisent. Donnez-lui seulement les droits dont l'outil a besoin : une clé qui ne fait que lire ne peut ni créer ni supprimer de QR code, même si elle est copiée par erreur au mauvais endroit.
| Préréglage | Droits accordés |
|---|---|
| Lecture / Reporting | Lire les QR codes, Lire les statistiques |
| Agent IA assistant | Lire les QR codes, Lire les statistiques (les mêmes droits que Lecture / Reporting, pour un agent IA qui consulte vos QR codes) |
| Intégration CRM | Lire les QR codes, Créer des QR codes, Lire les statistiques |
| Intégration CRM avec mise à jour | Lire les QR codes, Créer des QR codes, Modifier des QR codes, Lire les statistiques |
| Gestion complète | Les 5 droits, y compris Supprimer des QR codes |
Avec Personnalisé, vous cochez vous-même les droits voulus parmi les 5, au moins un.
Vous pouvez modifier les droits d'une clé existante à tout moment, puis cliquer sur Enregistrer les droits. Le changement s'applique immédiatement, sans changer la clé : l'outil qui l'utilise n'a rien à reconfigurer, il peut simplement faire plus ou moins de choses.
Un appel qui demande une opération non autorisée par les droits de la clé est refusé (erreur 403 forbidden).
Deux opérations demandent un droit moins évident :
- archiver ou réactiver un QR code demande Modifier des QR codes ;
- lire le quota de créations (créations du mois, solde des packs) demande Créer des QR codes. Les préréglages Lecture / Reporting et Agent IA assistant ne permettent donc pas de lire ce solde.
Quotas de créations et packs
Seule la création d'un QR code via l'API est comptée : lire, modifier, archiver, réactiver, supprimer un QR code, télécharger son image ou lire ses statistiques ne l'est pas. Les QR codes créés depuis le tableau de bord ne sont pas comptés non plus.
- Le quota est de 5 créations par mois civil avec le plan Pro et de 100 avec le plan Entreprise, pour tout le compte (toutes clés confondues).
- Une création reste comptée même si vous supprimez ensuite le QR code : supprimer un QR code ne vous rend pas de création.
- Il est remis à zéro le 1er de chaque mois à 00 h 00 UTC, soit à 1 h 00 en Suisse (2 h 00 en heure d'été). Les créations non utilisées ne sont pas reportées.
- Une fois le quota du mois épuisé, chaque création consomme une création de vos packs de créations API, en commençant par le pack le plus ancien.
- Quand le quota du mois et tous vos packs sont épuisés, la création est refusée avec l'erreur
429 quota_exceeded, qui indique la date de remise à zéro du quota. Rien n'est facturé à l'usage.
L'écran Clés API affiche où vous en êtes : créations du mois utilisées sur votre quota, créations prélevées sur vos packs, créations restantes dans vos packs et date de la prochaine remise à zéro. Votre outil peut lire les mêmes chiffres avec GET /usage, avec une clé qui a le droit Créer des QR codes (voir la documentation API).
Les packs (+50, +100, +500, +1000 ou +5000 créations) s'achètent en une seule fois depuis la carte Packs de créations API de l'écran Abonnement, avec un abonnement Pro ou Entreprise actif. Ils n'expirent pas tant que votre compte reste au plan Pro ou Entreprise. Les prix figurent sur la page Tarifs ; les conditions d'achat et le gel au plan Gratuit sont détaillés dans Gérer son abonnement.
Faire tourner une clé (rotation)
Le bouton Rotation génère un nouveau secret pour la clé et invalide immédiatement l'ancien. La clé garde son nom et ses droits, et ne compte pas comme une clé de plus.
- Cliquez sur Rotation à côté de la clé, puis confirmez.
- Copiez la nouvelle clé sur l'écran Copiez votre clé API maintenant : comme à la création, elle ne s'affiche qu'une seule fois.
- Remplacez l'ancienne clé dans tous les outils qui l'utilisent : tant que vous ne l'avez pas fait, leurs appels sont refusés.
Faites tourner une clé si vous l'avez perdue, si vous pensez qu'elle a pu être exposée (envoyée par e-mail, publiée dans un dépôt de code, visible dans une capture d'écran), ou simplement à intervalles réguliers.
Révoquer une clé
Le bouton Révoquer rend la clé inutilisable immédiatement et définitivement. Les outils qui l'utilisent cessent aussitôt de fonctionner. Une clé révoquée disparaît de la liste et ne peut être ni réactivée ni régénérée.
La révocation ne touche ni vos QR codes, y compris ceux créés avec cette clé, ni votre quota, ni vos packs. Elle libère une place dans la limite de clés de votre plan : vous pouvez ensuite créer une nouvelle clé.
Révoquez une clé dès qu'un outil n'en a plus besoin, ou si elle a pu être exposée et qu'aucun outil ne doit plus l'utiliser.
Clés gelées
Une clé gelée refuse tous les appels à l'API, y compris en lecture, avec la même erreur qu'une clé invalide (401 unauthorized). Elle n'est ni révoquée ni supprimée : son nom et ses droits sont conservés. Une clé est gelée quand votre plan autorise moins de clés que vous n'en avez. Les administrateurs du compte en sont informés par e-mail, et un bandeau l'indique dans le tableau de bord.
Quand votre compte passe au plan Gratuit
Si votre abonnement Pro ou Entreprise prend fin (résiliation arrivée à échéance ou échec de paiement définitif), toutes vos clés sont gelées : les outils qui les utilisent cessent de fonctionner. Le solde de vos packs de créations est lui aussi gelé, sans être perdu.
Au plan Gratuit, l'écran Clés API n'affiche pas vos clés : vous ne pouvez ni les consulter, ni les révoquer, ni les faire tourner, ni les réactiver.
Dès que vous reprenez un abonnement Pro ou Entreprise, vos clés gelées redeviennent automatiquement utilisables, dans la limite du nouveau plan : d'abord celles qui étaient actives au moment du gel, puis les plus anciennes. Les éventuelles clés au-delà de la limite restent gelées.
Quand vous passez du plan Entreprise au plan Pro
Le plan Pro n'autorise qu'une clé active. À la date du changement, la clé la plus ancienne (par date de création) reste active et les autres sont gelées. Elles restent visibles sur l'écran Clés API avec le badge Gelée. Si vous repassez au plan Entreprise, elles redeviennent actives automatiquement.
Choisir la clé active
Tant que votre plan ne change pas, aucune clé gelée n'est réactivée automatiquement. C'est vous qui choisissez :
- Le bouton Réactiver apparaît à côté de chaque clé gelée tant que votre nombre de clés actives est inférieur à la limite de votre plan. Au plan Pro, révoquez donc d'abord la clé active, s'il y en a une (la révocation est définitive).
- La clé réactivée fonctionne de nouveau immédiatement, avec la même valeur et les mêmes droits. Si elle a pu être exposée, faites-la tourner juste après.
- Une rotation ne réactive pas une clé gelée : elle reste gelée.
Révocation par QR Suisse
QR Suisse peut révoquer toutes les clés API de votre compte, actives ou gelées, à la demande d'un administrateur du compte (écrivez à contact@qrsuisse.ch depuis l'adresse e-mail que vous utilisez pour QR Suisse) ou si une clé a pu être exposée à un tiers ou utilisée sans votre accord. C'est notamment la solution si une clé a fuité alors que votre compte est au plan Gratuit, où vous ne pouvez pas la révoquer vous-même.
Cette révocation est immédiate et définitive, comme celle que vous faites vous-même. Les administrateurs du compte en sont informés par e-mail. Vos QR codes, votre quota et vos packs ne sont pas touchés. Au plan Pro ou Entreprise, vous pouvez créer de nouvelles clés aussitôt. Une clé gelée révoquée n'est pas réactivée lorsque vous reprenez un abonnement.
Limite de débit et erreur 429
Pour protéger le service, le nombre d'appels est limité, sur des fenêtres de 60 secondes :
| Limite | Nombre maximal |
|---|---|
| Toutes les requêtes | 30 par minute et par clé |
| Créations de QR codes | 8 par minute et par clé, en plus de la limite ci-dessus |
| Images PNG d'un QR code | 10 par minute pour tout le compte (le format SVG n'est pas limité ainsi) |
Au-delà, l'API répond 429 rate_limited, avec un en-tête Retry-After qui indique en secondes quand réessayer. Programmez votre outil pour attendre ce délai avant de réessayer, plutôt que de répéter l'appel aussitôt.
Les appels refusés pour une clé invalide (401 unauthorized) sont aussi limités, à 60 par minute depuis une même adresse IP, et à 300 par minute pour l'ensemble d'un même réseau IPv6 /48. Au-delà, l'API répond 429 rate_limited pendant le reste de la minute, même avec une clé valide. Un outil mal configuré qui insiste avec une ancienne clé peut donc bloquer temporairement les autres outils qui appellent l'API depuis la même adresse.
Ne confondez pas les deux erreurs 429 : rate_limited signifie « trop d'appels en peu de temps, réessayez dans quelques secondes », quota_exceeded signifie « plus aucune création disponible ce mois-ci » (voir « Quotas de créations et packs »).
Questions fréquentes
J'ai perdu ma clé : puis-je la retrouver ?
Non. La clé complète ne s'affiche qu'une seule fois et nous ne la conservons pas en clair. Faites-la tourner avec le bouton Rotation : vous obtenez une nouvelle clé, avec le même nom et les mêmes droits. Pensez à la remplacer dans tous les outils qui utilisaient l'ancienne.
Pourquoi l'API répond-elle 401 alors que j'utilise ma clé ?
L'API répond 401 unauthorized dans tous ces cas, sans les distinguer : clé mal copiée ou incomplète, clé révoquée, clé dont le secret a changé après une rotation, ou clé gelée (par exemple parce que votre compte est passé au plan Gratuit). Vérifiez sur l'écran Clés API que la clé existe toujours, qu'elle ne porte pas le badge Gelée et que ses 4 derniers caractères correspondent à ceux de la clé utilisée.
Pourquoi l'API répond-elle 403 ?
Avec forbidden, la clé est valide mais ses droits n'autorisent pas l'opération demandée : ajoutez le droit manquant dans Droits de la clé, puis cliquez sur Enregistrer les droits. Avec account_disabled, le compte est suspendu ou en attente de suppression : la clé n'est pas en cause, écrivez à contact@qrsuisse.ch. Avec plan_required, le compte n'a plus de plan Pro ou Entreprise actif. Avec https_required, votre outil a appelé l'API en http:// au lieu de https:// : la requête n'a pas été traitée, mais la clé a circulé en clair. Corrigez l'adresse en https://app.qrsuisse.ch/api/v1, puis faites tourner la clé avec le bouton Rotation.
Que signifie l'erreur 429 ?
Avec rate_limited, votre outil a envoyé trop de requêtes en peu de temps : attendez le délai indiqué par l'en-tête Retry-After, puis réessayez. Avec quota_exceeded, le quota de créations du mois et vos packs sont épuisés : la création redevient possible le 1er du mois suivant, ou dès l'achat d'un pack.
Une création a été interrompue par une coupure réseau : comment la relancer sans doublon ?
Si votre outil envoie l'en-tête Idempotency-Key avec chaque création (une valeur aléatoire nouvelle par création), il peut renvoyer la même requête avec la même valeur dans les 24 heures : l'API renvoie le QR code déjà créé, sans en créer un second ni décompter une autre création. Sans cet en-tête, vérifiez la liste de vos QR codes avant de relancer : une création aboutie reste comptée, même si vous supprimez ensuite le doublon. Les détails sont dans la documentation API.
Créer une clé consomme-t-il mon quota ?
Non. Seuls les QR codes créés via l'API sont comptés dans le quota mensuel.
Mes QR codes créés via l'API sont-ils supprimés si je révoque la clé ?
Non. Révoquer une clé ne modifie ni ne supprime aucun QR code. Les QR codes créés avec cette clé continuent de fonctionner.
Pourquoi je ne vois pas l'écran Clés API ?
L'écran Clés API est réservé aux membres qui ont la permission Gérant des clés API (ou Administrateur). Au plan Gratuit, il indique que l'accès API est disponible avec les plans Pro et Entreprise, et vos clés éventuellement gelées n'y sont pas affichées. Demandez à un administrateur du compte de vous donner la permission ou de passer au plan Pro.
Ma clé a peut-être été exposée : que faire ?
Faites-la tourner immédiatement avec le bouton Rotation si vos outils doivent continuer à l'utiliser, ou révoquez-la avec le bouton Révoquer sinon. Dans les deux cas, l'ancienne clé cesse aussitôt de fonctionner. Si vous ne pouvez pas le faire vous-même, par exemple parce que votre compte est au plan Gratuit, écrivez à contact@qrsuisse.ch depuis l'adresse e-mail d'un administrateur du compte.
Combien de clés puis-je avoir ?
Une clé active avec le plan Pro, jusqu'à 10 clés actives simultanément avec le plan Entreprise. Pour créer une nouvelle clé, vos clés gelées comptent aussi dans cette limite, tant que vous ne les avez pas révoquées.