Clés API (page Developers)
Créez des clés API personnelles pour utiliser les données Quran Gallery dans vos propres scripts et applications — générez, copiez, et révoquez depuis la page Developers.
Sur cette page
🌐 Cette traduction est en cours de relecture par la communauté. Vous avez repéré une erreur ou une formulation peu naturelle ? Cliquez sur Modifier cette page sur GitHub en bas de page pour proposer une amélioration.
Si vous construisez quelque chose sur Quran Gallery — un projet annexe, un tableau de bord personnel, un script d’automatisation — vous pouvez générer des clés API personnelles qui prouvent qu’une requête vient de vous, sans avoir besoin d’une session navigateur.
Les clés API se gèrent entièrement depuis la page Developers de votre compte.
Comment atteindre la page Developers
Connectez-vous à accounts.qurangallery.com, puis allez à accounts.qurangallery.com/developers.
Qu’est-ce qu’une clé API
Une clé API est une longue chaîne secrète qui ressemble à :
qg_abc123def456...Le préfixe qg_ la marque comme une clé Quran Gallery. Quand vous l’envoyez dans l’en-tête Authorization: Bearer ... d’une requête à Quran Gallery, le serveur traite la requête comme si vous l’aviez faite. Une clé API est donc effectivement un mot de passe à votre compte limité à un usage programmatique — traitez-la comme tel.
Créer une clé
- Sur la page Developers, trouvez la carte Create New Key.
- Tapez un nom descriptif —
"Madrasah progress export script","My Raspberry Pi dashboard","Local dev". Le nom est juste pour vous — il apparaît dans la liste des clés. - Cliquez sur Create key.
La nouvelle clé apparaît en haut de la page dans une carte verte avec sa valeur complète. C’est la seule fois où vous verrez la clé complète. Cliquez sur l’icône de copie pour la mettre dans votre presse-papiers, puis sauvegardez-la quelque part en sécurité.
Après avoir cliqué sur Done, la carte verte disparaît, et à partir de ce moment seuls les premiers caractères (le « start ») de la clé sont visibles dans la liste. Il n’y a aucun moyen de récupérer la valeur complète à nouveau — si vous la perdez, vous devez créer une nouvelle clé et supprimer l’ancienne.
La liste des clés
Sous le formulaire de création, vous voyez chaque clé actuellement sur votre compte.
Pour chaque clé :
- Nom — ce que vous avez tapé en la créant.
- Statut — Active (pastille verte) ou Disabled (pastille grise).
- Start — les premiers caractères, comme
qg_abc12.... - Created — la date de génération.
À droite de chaque ligne, une icône poubelle supprime la clé. La suppression est permanente et immédiate — tout script ou application utilisant la clé supprimée commence à recevoir 401 Unauthorized à la prochaine requête.
Utiliser une clé
Envoyez-la dans l’en-tête Authorization sur les requêtes :
Authorization: Bearer qg_abc123def456...La carte d’utilisation sur la page Developers affiche le format exact à copier. La même clé vous authentifie sur chaque service Quran Gallery qui supporte l’authentification par clé.
Les requêtes par clé API contournent la session navigateur, donc vous pouvez les utiliser depuis des jobs CI, des tâches planifiées, des applications mobiles.
Limites de débit
Chaque clé API est limitée à 60 requêtes par minute, fenêtre glissante. C’est largement suffisant pour un usage personnel et la plupart des scripts. Si vous dépassez, l’API renvoie HTTP 429 avec des en-têtes indiquant quand vous pouvez réessayer.
Les clés API pour des comptes suspendus ou supprimés cessent de fonctionner immédiatement.
Faire tourner les clés
La bonne pratique est de faire tourner les clés à chaque fois que :
- Un ordinateur ou appareil contenant la clé a été perdu ou vendu.
- Vous avez partagé la clé avec un collaborateur qui n’a plus besoin de l’accès.
- Il y a longtemps et vous préférez ne pas avoir un secret non-rotaté qui traîne.
La rotation est un flux manuel en deux étapes :
- Créez une nouvelle clé avec un nom descriptif.
- Mettez à jour vos scripts/applications pour utiliser la nouvelle clé.
- Une fois tout sur la nouvelle clé, supprimez l’ancienne.
Pas de fonctionnalité de rotation automatique aujourd’hui.
J’ai perdu ma clé
Quran Gallery ne peut pas récupérer une clé perdue. Supprimez l’ancienne clé de la liste (pour qu’elle cesse de fonctionner si quelqu’un d’autre l’a) et créez-en une nouvelle. Mettez à jour votre script pour utiliser la nouvelle valeur.
Liste de vérification sécurité
- Ne committez jamais une clé sur git. Utilisez un fichier
.env(et ajoutez-le à.gitignore). - Ne collez jamais une clé dans un Slack public, un Discord, un issue GitHub ou un chat avec un outil d’IA. Traitez les clés exactement comme des mots de passe.
- Utilisez une clé par projet, pas une clé pour tout.
- Si vous suspectez qu’une clé est compromise, supprimez-la d’abord, puis créez-en une nouvelle. L’ordre importe.
- N’incrustez pas les clés dans du code côté client (JavaScript dans le navigateur, binaires d’apps mobiles).
Erreurs fréquentes
| Erreur | Solution |
|---|---|
| 401 Unauthorized en appelant l’API | Votre clé a été supprimée, désactivée ou n’a jamais été créée. Créez-en une nouvelle. |
| 403 Account suspended | Le compte propriétaire de la clé est suspendu. Voir Comptes suspendus. |
| 429 Too Many Requests | Vous avez atteint le plafond par minute. Reculez et réessayez. |
| « Failed to load API keys » sur la page | Erreur réseau transitoire. Rafraîchissez. |