Authentification et clés API

Chaque requête de votre serveur porte une clé API dans l’en-tête Authorization. Les clés se créent et se révoquent dans le tableau de bord (Développeurs › Clés API), jamais par l’API elle-même.

En-tête

Authorization: Bearer gsp_test_sk_XXXXXXXX_YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY

Deux types de clés

Type	Préfixe	Où l’utiliser	Ce qu’elle permet
Secrète	`gsp_test_sk_` / `gsp_live_sk_`	Votre serveur uniquement	Les permissions choisies à sa création (liste ci-dessous)
Publique	`gsp_test_pk_` / `gsp_live_pk_`	Navigateur, application mobile	Seulement lire le statut d’un paiement, avec son `client_secret` (voir Paiements)

Une clé secrète ne quitte jamais votre serveur

Ne la mettez ni dans une application mobile, ni dans du JavaScript envoyé au navigateur, ni dans un dépôt Git. Quiconque la détient peut agir sur votre compte dans la limite de ses permissions. En cas de doute, révoquez-la : l’effet est immédiat.

Permissions d’une clé secrète

Donnez à chaque clé le minimum nécessaire. Une requête qui sort de ses permissions répond 403 FORBIDDEN.

Permission	Autorise
`payments:read`	Lire les paiements, les moyens de paiement
`payments:write`	Créer et annuler des paiements ; simulateur (mode test)
`refunds:write`	Rembourser
`payouts:read`	Lire les versements
`payouts:write`	Demander des versements ; simulateur de versement (mode test)
`customers:read`	Lire les clients
`customers:write`	Créer et anonymiser des clients
`balance:read`	Lire le solde et les mouvements
`reports:read`	Rapports et statistiques

Trois droits ne peuvent jamais être donnés à une clé API : gérer les clés (api_keys:manage), configurer le compte et le webhook (merchant:manage) et approuver un versement (payouts:approve). Ils restent dans le tableau de bord, protégés par la double authentification.

Vérifier une clé

cURL

curl -s https://backend.v1.pay.galsen.tech/v1/auth/me -H "Authorization: Bearer $GALSEN_SECRET_KEY"
# {"success":true,"data":{"type":"api_key","merchantId":"…","permissions":["payments:read",…]},"requestId":"…"}

Erreurs d’authentification

Statut	Code	Signification
401	`UNAUTHENTICATED`	Aucune clé dans la requête.
401	`INVALID_API_KEY`	Clé inconnue, révoquée, expirée ou d’un autre environnement. La réponse est volontairement la même dans tous ces cas : elle ne renseigne pas un attaquant.
403	`FORBIDDEN`	La clé n’a pas la permission demandée par cet endpoint.
403	`MERCHANT_SUSPENDED`	Le compte marchand est suspendu : aucune opération d’argent possible.

Bonnes pratiques

Une clé par service ou par serveur, nommée clairement : la révocation d’une clé ne coupe que ce qui l’utilise.
Une date d’expiration pour les clés temporaires (tests, prestataires).
Surveillez la colonne Dernière utilisation : une clé jamais utilisée peut être révoquée.
25 clés actives au plus par compte marchand.