Guide
OAuth pour les applications multi-commerçants
Laissez les commerçants brancher votre application en un clic, sans copier de clé.
Quand utiliser OAuth
Une clé d’API suffit quand vous intégrez un commerçant : il crée la clé et vous la transmet. Quand votre application sert plusieurs commerçants (fidélité, place de marché, outil comptable), OAuth permet à chacun de la brancher en un clic : il se connecte à Gillia, choisit son enseigne, voit les droits demandés et accepte. Vous ne voyez jamais son mot de passe, et il peut couper l’accès à tout moment.
Le parcours est OAuth 2 code d’autorisation avec PKCE (S256, obligatoire). Votre client s’authentifie avec son secret auprès de l’adresse du jeton.
| Adresse | |
|---|---|
| Autorisation | https://gillia.app/oauth/authorize |
| Jeton | https://gillia.app/oauth/token |
| Révocation | https://gillia.app/oauth/revoke |
| Métadonnées (RFC 8414) | https://gillia.app/.well-known/oauth-authorization-server/oauth |
1. Inscrire votre application
Avec la clé de votre bac à sable (gsk_test_…, voir Tester dans le bac à sable) :
curl https://gillia.app/pos-api/api/v1/me/apps \
-H "Authorization: Bearer gsk_test_VOTRE_CLE" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Fidélité",
"redirectUris": ["https://acme.example.com/oauth/callback"],
"scopes": ["pos.customers.read", "pos.customers.write", "pos.sales.read"]
}'
La réponse donne un clientId (gci_…) et un clientSecret (gcs_…). Le secret ne s’affiche qu’une fois : gardez-le sur votre serveur. Perdu, il se remplace par POST /me/apps/{clientId}/secret.
- Les adresses de retour sont comparées à l’identique. En https ; http est accepté sur
localhostpour le développement. - Les droits sont le maximum que votre application pourra demander. Chaque autorisation peut en demander moins.
- Une application neuve est en test : seuls des bacs à sable peuvent l’autoriser. Les vrais commerçants le pourront une fois l’application certifiée.
2. Envoyer le commerçant à l’écran de consentement
Tirez un code_verifier (43 à 128 caractères aléatoires), calculez code_challenge = BASE64URL(SHA-256(code_verifier)), gardez le verifier de votre côté, puis redirigez le commerçant vers :
https://gillia.app/oauth/authorize
?response_type=code
&client_id=gci_…
&redirect_uri=https://acme.example.com/oauth/callback
&scope=pos.customers.read pos.sales.read
&state=VALEUR_ALEATOIRE
&code_challenge=…
&code_challenge_method=S256
Le commerçant se connecte, choisit une des enseignes qu’il administre, lit les droits en clair et accepte. Gillia renvoie alors vers votre adresse avec code, votre state et iss=https://gillia.app/oauth. Vérifiez state (il doit être le vôtre) et iss (il doit être celui de Gillia) avant de continuer. Un refus revient avec error=access_denied.
3. Échanger le code contre un jeton
Dans les 5 minutes, depuis votre serveur :
curl https://gillia.app/oauth/token \
-u "gci_…:gcs_…" \
-d grant_type=authorization_code \
-d code=LE_CODE \
-d redirect_uri=https://acme.example.com/oauth/callback \
-d code_verifier=LE_VERIFIER
{
"access_token": "gsk_…",
"token_type": "Bearer",
"scope": "pos.customers.read pos.sales.read"
}
Le jeton est une clé d’API de ce commerçant, rattachée à votre application. Utilisez-la comme toute clé : Authorization: Bearer gsk_…, puis GET /sites pour trouver ses établissements. Elle porte exactement les droits accordés et vaut jusqu’à ce que le commerçant la révoque (dans Paramètres › Intégrations › Clés API, où votre application apparaît par son nom) ou que vous la rendiez. Pas d’expiration ni de jeton de rafraîchissement : gardez-la comme un mot de passe.
Chaque autorisation donne un jeton distinct, et autoriser de nouveau ne révoque pas les précédents : deux personnes d’une même enseigne, ou deux comptes reliés de votre côté, gardent chacun leur accès. Quand une connexion est remplacée chez vous, rendez l’ancien jeton (étape 4).
4. Déconnecter
Quand le commerçant déconnecte votre application chez vous, rendez le jeton :
curl https://gillia.app/oauth/revoke -u "gci_…:gcs_…" -d token=gsk_…
Supprimer l’application (DELETE /me/apps/{clientId}) révoque tous les jetons qu’elle a reçus.
Erreurs
| Où | Erreur | Signification |
|---|---|---|
| Retour | invalid_request | PKCE absent ou pas en S256 |
| Retour | invalid_scope | Un droit que votre application n’a pas déclaré |
| Retour | access_denied | Le commerçant a refusé, ou ne peut pas autoriser cette application |
| Jeton | invalid_client (401) | Client inconnu ou mauvais secret |
| Jeton | invalid_grant | Code inconnu, expiré, déjà utilisé, mauvaise redirect_uri ou mauvais verifier |
| Jeton | slow_down (429) | Trop d’échecs : attendez quelques minutes |