Clés d'API et portées

Une clé d'API, un en-tête, et c'est tout. Ce qui mérite d'être lu ici, c'est ce que la clé donne le droit de faire, et ce qu'elle engage.

L'en-tête

Authorization: Bearer pc_live_ff1ec195bcf26cb2…

Rien d'autre. Pas d'identifiant d'organisation, pas d'identifiant de projet : la clé appartient à un projet, et la plateforme en déduit tout le reste.

C'est ce qui rend le cloisonnement infranchissable. Il n'y a aucun identifiant à deviner dans une URL, donc rien à incrémenter pour voir ce qui arrive.

La clé ne s'affiche qu'une fois

À l'émission, la clé est montrée une seule fois. Nous n'en conservons qu'une empreinte : personne chez nous ne peut la relire, y compris pour vous rendre service.

Conservez-la comme un mot de passe de production — dans votre gestionnaire de secrets, pas dans votre dépôt. Une clé perdue se révoque et se remplace en trente secondes ; une clé publiée sur GitHub, non.

Les portées

Une clé porte des portées. Une clé posée dans un back-office pour afficher des statistiques n'a aucune raison de pouvoir écrire au registre.

Portée	Ce qu'elle autorise
customers:read	Lire le rattachement d'un client
customers:write	Rattacher un client à un ambassadeur
events:write	Remonter des revenus
partnerships:read	Lister les ambassadeurs
commissions:read	Lire les commissions
partners:write	Créer un ambassadeur

Une clé qui n'en déclare aucune les obtient toutes par défaut : la première intégration ne doit pas buter sur une notion qu'on n'a pas demandée. Émettez ensuite des clés restreintes, une par usage.

Une clé vaut signature. Tout revenu déclaré avec une clé valide est réputé venir de vous, et les commissions calculées dessus vous engagent. Révoquez sans attendre une clé dont vous doutez : c'est instantané, et les autres continuent de fonctionner.

Quotas

Les appels sont limités par clé, et non par adresse IP : vos appels viennent de serveurs, souvent derrière la même sortie mutualisée qu'une centaine d'autres clients. Au-delà, la réponse est un 429 avec un en-tête Retry-After : attendez ce délai plutôt que de réessayer aussitôt.

Environnements

Une clé est propre à un projet. Pour séparer vos environnements, créez un projet de recette et un projet de production, chacun avec ses clés et ses programmes. Vos essais n'écriront jamais dans la comptabilité réelle, et vous pourrez purger la recette sans précaution.