Technique - Applications OAuth

Connecter un logiciel tiers à un compte Grand Shooting avec OAuth 2.0 : l'utilisateur autorise l'application, qui reçoit son propre jeton, sans échange de mot de passe ni de clé API.

Une clé API convient pour une intégration interne : un compte, un script, une clé. Dès que votre logiciel s'adresse à plusieurs clients Grand Shooting, utilisez une application OAuth (appelée « plugin » dans l'API) :

l'utilisateur se connecte à Grand Shooting et autorise votre application, sans vous confier de mot de passe ni de clé ;
votre application reçoit un jeton propre à ce compte ;
le compte active et désactive votre application depuis sa page Connecteurs.

Déclarer une application

Une application appartient au compte de son éditeur. Elle est définie par :

Élément	Rôle
`client_id`, `client_secret`	Identifiants OAuth de l'application, fournis par Grand Shooting. Le secret ne doit jamais quitter votre serveur.
URL de callback (`redirect_uri`)	Adresse où Grand Shooting renvoie l'utilisateur après son autorisation. Elle doit correspondre exactement à celle envoyée dans la requête (les adresses locales `localhost` / `127.0.0.1` sont acceptées sur tout port, pour le développement).
URL d'activation	Page de votre application ouverte quand un compte active le connecteur : c'est elle qui lance le flux OAuth.
URL de suivi (poll status)	Interrogée pendant l'activation pour afficher l'avancement à l'utilisateur.
URL de désactivation	Appelée quand le compte désactive le connecteur.

Ces URL se règlent dans le portail développeur Grand Shooting, où vous retrouvez aussi votre client_id et pouvez renouveler le client_secret. Pour créer une application et la rendre disponible aux comptes clients, contactez l'équipe Grand Shooting (help@grand-shooting.com).

Le flux d'autorisation

Grand Shooting implémente le flux Authorization Code d'OAuth 2.0, avec PKCE (S256) en option, recommandé. Le serveur d'autorisation est https://api.grand-shooting.com/oauth/default ; ses métadonnées sont publiées sur https://api.grand-shooting.com/.well-known/oauth-authorization-server.

1. Rediriger l'utilisateur

GET https://api.grand-shooting.com/oauth/default/authorize
  ?response_type=code
  &client_id=gs_123_xxxxxxxx
  &redirect_uri=https%3A%2F%2Fmonapp.example%2Fcallback
  &state=<valeur aléatoire>
  &code_challenge=<challenge>&code_challenge_method=S256

L'utilisateur se connecte à Grand Shooting, puis accepte ou refuse l'accès. S'il accepte, il revient sur votre redirect_uri avec ?code=…&state=… ; s'il refuse, avec ?error=access_denied&state=…. Vérifiez toujours que state est celui que vous avez envoyé.

2. Échanger le code contre un jeton

Le code est à usage unique : échangez-le tout de suite, depuis votre serveur.

curl -X POST https://api.grand-shooting.com/oauth/default/token \
  -d grant_type=authorization_code \
  -d code=$CODE \
  -d redirect_uri=https://monapp.example/callback \
  -d client_id=$CLIENT_ID \
  -d client_secret=$CLIENT_SECRET \
  -d code_verifier=$VERIFIER

{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 31536000,
  "refresh_token": "…",
  "account_id": 10229487
}

Le jeton d'accès et le jeton de rafraîchissement sont valables un an. Enregistrez-les par account_id : un même utilisateur de votre logiciel peut connecter plusieurs comptes Grand Shooting.

3. Appeler l'API

Le jeton OAuth se passe avec le préfixe access_token, pas Bearer (réservé aux clés API) :

curl -H "Authorization: access_token $ACCESS_TOKEN" https://api.grand-shooting.com/v3/account/me

Toute l'API est ensuite accessible comme avec une clé : voir Premiers pas avec l'API. GET https://api.grand-shooting.com/oauth/default/user/info (avec Authorization: Bearer <access_token>) renvoie l'utilisateur et le compte qui ont autorisé l'application.

4. Rafraîchir le jeton

curl -X POST https://api.grand-shooting.com/oauth/default/token \
  -d grant_type=refresh_token \
  -d refresh_token=$REFRESH_TOKEN \
  -d client_id=$CLIENT_ID \
  -d client_secret=$CLIENT_SECRET

Chaque rafraîchissement renvoie une nouvelle paire de jetons et invalide l'ancien jeton de rafraîchissement : enregistrez toujours la nouvelle paire.

Il n'y a pas de scopes : le jeton donne à l'application les droits de l'utilisateur qui l'a autorisée, sur son compte. Demandez à vos clients d'autoriser l'application avec un utilisateur dont les droits correspondent à ce dont elle a besoin.

Activation depuis la page Connecteurs

Côté client, l'installation se fait en quelques clics :

Dans la page Connecteurs de son compte, l'utilisateur active votre application.
Grand Shooting ouvre votre URL d'activation (avec plugin_id en paramètre), qui redirige vers /authorize (étape 1 ci-dessus).
Pendant ce temps, la page Connecteurs interroge votre URL de suivi toutes les deux secondes (avec account_id, plugin_id et user_uid) ; elle attend un statut JSON wait, pick, ok ou error.
Une fois le jeton obtenu, votre serveur confirme l'activation pour ce compte :

curl -X PATCH -H "Authorization: access_token $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"active":true}' https://api.grand-shooting.com/v3/account/plugin/{plugin_id}

À la désactivation, Grand Shooting appelle votre URL de désactivation en DELETE, avec account_id en paramètre : supprimez alors les jetons de ce compte.

Aller plus loin

Votre application peut s'abonner aux webhooks du compte avec son jeton, pour réagir aux nouveaux médias sans interroger l'API.
Le serveur MCP de Grand Shooting utilise ce même serveur d'autorisation : c'est une application OAuth comme une autre.

Un compte Grand Shooting est servi par un serveur de la plateforme (voir api_host dans /account/me), et un jeton OAuth n'est valable que sur le serveur qui l'a émis. Si vos clients sont sur des serveurs différents, contactez Grand Shooting pour connaître l'adresse d'autorisation à utiliser.

Comment pouvons-nous vous aider ?

Applications OAuth