Clés d'API
Chaque intégration programmatique avec GCM s'authentifie avec une clé d'API. Zapier en utilise une. Votre backend personnalisé en utilise une. Votre pipeline data warehouse en utilise une. Cette page explique comment les créer, en limiter la portée et les retirer en toute sécurité.
Gérez les clés dans Intégrations → Zapier → API Keys. (Malgré l'URL, ce n'est pas réservé à Zapier — tout appelant externe de l'API GCM utilise les clés d'ici.)
Créer une clé
Cliquez sur Nouvelle clé. Donnez-lui une étiquette qui nomme ce qui utilisera la clé, pas qui l'a créée :
- Zapier — Production — pour les Zaps.
- ETL data warehouse — pour votre export nocturne.
- Site d'annuaire interne — pour un intranet réservé au personnel listant les membres.
Lorsque vous cliquez sur créer, GCM affiche la clé brute une seule fois.
Copiez-la immédiatement et stockez-la dans un vrai gestionnaire de secrets — 1Password, AWS Secrets Manager, Doppler, Vault, la plateforme de votre choix. Ne la collez pas dans Slack, un e-mail ou une page de wiki.
WARNING
Nous ne stockons pas la clé brute. La base de données ne contient qu'un hash, plus un préfixe de 6 caractères que vous pouvez utiliser pour identifier quelle clé est laquelle sans révéler le secret. Si vous perdez la clé brute, votre seule option est de la révoquer et d'en émettre une nouvelle.
Format de la clé
Les clés ressemblent à gcm_live_<32 caractères aléatoires> ou gcm_test_<32 caractères aléatoires> selon l'environnement où elles ont été émises. Le préfixe est visible dans la liste des clés afin que vous puissiez savoir d'un coup d'œil quelle clé est en production ou en staging sans jamais voir le secret.
gcm_live_a1b2c3d4e5f6...
└─┬─┘└─┬─┘└──────┬──────┘
│ │ └── 32 caractères d'entropie CSPRNG
│ └── environnement
└── produit (toujours `gcm`)Portées
Chaque clé porte une liste de portées qui contraignent ce qu'elle peut faire. La valeur par défaut pour les clés créées via l'interface Zapier est read:* — accès en lecture seule à toutes les ressources.
| Portée | Octroie |
|---|---|
read:* | Lister et lire toutes les ressources publiques |
read:members | Membres uniquement |
read:donations | Dons uniquement |
write:members | Créer / mettre à jour des membres |
write:donations | Enregistrer des dons (pour les intégrations comptables) |
subscriptions:manage | Créer / supprimer des abonnements webhook |
* | Accès total — équivalent admin. À utiliser avec parcimonie. |
Les portées sont appliquées par la passerelle d'API, pas par la logique applicative — une clé read:* appelant un endpoint d'écriture reçoit un 403 immédiatement, sans jamais atteindre le RPC sous-jacent.
TIP
Commencez chaque nouvelle intégration en read:*. N'élargissez la portée que lorsque vous avez prouvé que le chemin en lecture fonctionne et que vous avez un vrai besoin d'écriture. Les clés trop largement portées sont la façon dont les exploits deviennent des catastrophes.
Utiliser une clé
Envoyez la clé comme un token Bearer sur chaque requête :
curl https://api.geniuschurchmanager.com/v1/members \
-H "Authorization: Bearer gcm_live_..."C'est tout. Pas de danse OAuth, pas de signature par requête — juste le bearer. Combiné avec HTTPS, c'est suffisant pour les intégrations pour lesquelles l'API est conçue.
Chaque requête est consignée avec le préfixe de la clé, l'endpoint atteint et le statut de réponse. Vous pouvez voir l'horodatage de dernière utilisation sur la clé dans l'interface GCM — utile pour repérer les clés inutilisées depuis des mois (de bonnes candidates à la rotation ou à la révocation).
Rotation
Vous devriez faire tourner les clés d'API :
- Sur calendrier — tous les 12 mois au minimum.
- Au départ d'un employé — toute personne ayant eu accès à la clé brute ne devrait plus pouvoir l'utiliser après son départ.
- Sur soupçon de compromission — si une clé apparaît dans un commit Git, un message Slack ou une capture d'écran, considérez-la comme compromise.
Procédure de rotation :
- Émettez une nouvelle clé avec les mêmes portées.
- Déployez la nouvelle clé chez le consommateur (connexion Zapier, variable d'environnement, gestionnaire de secrets).
- Vérifiez que le consommateur utilise la nouvelle clé en observant l'horodatage last_used progresser.
- Révoquez l'ancienne clé.
GCM ne prend pas en charge les fenêtres de rotation chevauchantes — l'ancienne clé fonctionne jusqu'à révocation, et la nouvelle fonctionne dès sa création. Planifiez votre bascule.
Révoquer
Appuyez sur l'icône poubelle à côté de n'importe quelle clé. La clé est marquée revoked_at immédiatement ; la toute prochaine requête la portant reçoit un 401.
WARNING
Révoquer une clé en production casse instantanément tout consommateur l'utilisant. Les Zaps s'arrêtent, votre job ETL lève des erreurs, votre annuaire intranet devient vide. Coordonnez la rotation, puis révoquez.
Les clés révoquées restent dans la liste (grisées) pour que vous puissiez auditer quand elles ont été émises, quand elles ont été utilisées en dernier et quand elles ont été retirées. Pour supprimer définitivement une ancienne clé révoquée, contactez le support de la plateforme — les auditeurs préfèrent généralement les révocations aux suppressions.
Auditer l'utilisation
La liste des clés affiche pour chaque clé :
- L'horodatage de création.
- L'horodatage de dernière utilisation (en continu — mis à jour en quelques secondes après une requête).
- Les portées.
- L'horodatage de révocation, si révoquée.
Pour un audit plus poussé — comptages par endpoint, distribution des codes de réponse, détection d'abus — les administrateurs de plateforme ont accès à la table api_request_log dans les exports BigQuery. Contactez-nous si vous avez besoin d'une coupe spécifique.
Limites
| Limite | Par défaut |
|---|---|
| Clés par organisation | 20 |
| Requêtes par seconde par clé | 60 |
| Requêtes par heure par clé | 10 000 |
| Requêtes simultanées par clé | 20 |
Ces limites sont délibérément généreuses pour les intégrations légitimes et suffisamment serrées pour rendre l'énumération par force brute impraticable. Si vous heurtez une limite, vous avez probablement une boucle incontrôlée quelque part.
Ce qu'une clé d'API ne peut pas faire
Pour des raisons de sécurité, les clés d'API ne peuvent délibérément pas :
- Se connecter de manière interactive (pas de session, pas d'accès à l'interface).
- Gérer d'autres clés d'API (seule l'interface Zapier le peut, et seuls les admins y accèdent).
- Usurper l'identité d'un utilisateur (le système JWT qui contrôle l'usurpation par admin de plateforme est séparé).
- Contourner la sécurité au niveau ligne — chaque requête reste limitée à
current_org_id()dérivé de l'organisation de la clé.
Ce sont des garde-fous, pas des fonctionnalités : même une clé compromise ne peut pas s'échapper au-delà de l'organisation qui la possède.
Références croisées
- Intégration Zapier — le consommateur le plus courant de ces clés.
- Webhooks sortants — utilise les mêmes clés pour créer des abonnements.
- Authentification API — référence complète de l'API pour utiliser une clé.