Una chiave API va bene per un'integrazione interna: un account, uno script, una chiave. Non appena il vostro software si rivolge a più clienti Grand Shooting, usate un'applicazione OAuth (chiamata "plugin" nell'API):

• l'utente si collega a Grand Shooting e autorizza la vostra applicazione, senza affidarvi password né chiavi;
• la vostra applicazione riceve un token proprio di quell'account;
• l'account attiva e disattiva la vostra applicazione dalla sua pagina Connettori.

Dichiarare un'applicazione

Un'applicazione appartiene all'account del suo editore. È definita da:

Elemento	Ruolo
client_id, client_secret	Credenziali OAuth dell'applicazione, fornite da Grand Shooting. Il segreto non deve mai lasciare il vostro server.
URL di callback (redirect_uri)	Indirizzo a cui Grand Shooting rimanda l'utente dopo l'autorizzazione. Deve corrispondere esattamente a quello inviato nella richiesta (gli indirizzi locali localhost / 127.0.0.1 sono accettati su qualsiasi porta, per lo sviluppo).
URL di attivazione	Pagina della vostra applicazione aperta quando un account attiva il connettore: è lei che avvia il flusso OAuth.
URL di monitoraggio (poll status)	Interrogato durante l'attivazione per mostrare l'avanzamento all'utente.
URL di disattivazione	Chiamato quando l'account disattiva il connettore.

Questi URL si configurano nel portale sviluppatori di Grand Shooting, dove trovate anche il vostro client_id e potete rinnovare il client_secret. Per creare un'applicazione e renderla disponibile agli account clienti, contattate il team Grand Shooting (help@grand-shooting.com).

Il flusso di autorizzazione

Grand Shooting implementa il flusso Authorization Code di OAuth 2.0, con PKCE (S256) facoltativo, consigliato. Il server di autorizzazione è https://api.grand-shooting.com/oauth/default; i suoi metadati sono pubblicati su https://api.grand-shooting.com/.well-known/oauth-authorization-server.

1. Reindirizzare l'utente

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

L'utente si collega a Grand Shooting, poi accetta o rifiuta l'accesso. Se accetta, torna sul vostro redirect_uri con ?code=…&state=…; se rifiuta, con ?error=access_denied&state=…. Verificate sempre che state sia quello che avete inviato.

2. Scambiare il codice con un token

Il codice è monouso: scambiatelo subito, dal vostro server.

curl -X POST https://api.grand-shooting.com/oauth/default/token \
  -d grant_type=authorization_code \
  -d code=$CODE \
  -d redirect_uri=https://miaapp.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
}

Il token di accesso e il token di aggiornamento sono validi un anno. Salvateli per account_id: uno stesso utente del vostro software può collegare più account Grand Shooting.

3. Chiamare l'API

Il token OAuth si passa con il prefisso access_token, non Bearer (riservato alle chiavi API):

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

Tutta l'API è poi accessibile come con una chiave: vedere Primi passi con l'API. GET https://api.grand-shooting.com/oauth/default/user/info (con Authorization: Bearer <access_token>) restituisce l'utente e l'account che hanno autorizzato l'applicazione.

4. Aggiornare il token

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

Ogni aggiornamento restituisce una nuova coppia di token e invalida il vecchio token di aggiornamento: salvate sempre la nuova coppia.

Non ci sono scope: il token dà all'applicazione i diritti dell'utente che l'ha autorizzata, sul suo account. Chiedete ai vostri clienti di autorizzare l'applicazione con un utente i cui diritti corrispondano a ciò di cui ha bisogno.

Attivazione dalla pagina Connettori

Lato cliente, l'installazione si fa in pochi clic:

1. Nella pagina Connettori del suo account, l'utente attiva la vostra applicazione.
2. Grand Shooting apre il vostro URL di attivazione (con plugin_id come parametro), che reindirizza verso /authorize (passo 1 qui sopra).
3. Nel frattempo, la pagina Connettori interroga il vostro URL di monitoraggio ogni due secondi (con account_id, plugin_id e user_uid); si aspetta uno stato JSON wait, pick, ok o error.
4. Una volta ottenuto il token, il vostro server conferma l'attivazione per quell'account:

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}

Alla disattivazione, Grand Shooting chiama il vostro URL di disattivazione in DELETE, con account_id come parametro: eliminate allora i token di quell'account.

Per andare oltre

• La vostra applicazione può abbonarsi ai webhook dell'account con il suo token, per reagire ai nuovi media senza interrogare l'API.
• Il server MCP di Grand Shooting usa lo stesso server di autorizzazione: è un'applicazione OAuth come le altre.