App OAuth

1. Registra la tua app

Registri la tua app in autonomia. Accedi con il tuo account Gravl su app.gravl.ai/settings/developer e apri la sezione App OAuth, accanto ai tuoi personal access token.

Ti verrà chiesto di indicare:

• Il nome della tua app e una breve descrizione di cosa fa; il nome non può contenere “Gravl”
• Un logo facoltativo: un PNG, JPEG o WebP quadrato (niente SVG), di almeno 128×128 px e al massimo 1 MB. Compare nella schermata di consenso accanto al nome della tua app
• La homepage della tua app: un URL https
• Fino a 5 redirect URI: URL https assoluti (http://localhost è consentito per lo sviluppo)
• Gli scope di cui la tua app ha bisogno: chiedi il minimo; gli utenti vedono esattamente ciò che richiedi
• Il tipo di client: confidenziale per le app lato server che possono custodire un client_secret, oppure pubblico per le app browser e native, che non ricevono un secret e devono usare PKCE

Ricevi subito un client_id (gci_…). I client confidenziali ricevono anche un client_secret (gcs_…, mostrato una sola volta: conservalo come una password). Puoi rigenerare il secret in seguito dalla stessa pagina. Ogni account può avere fino a 5 app OAuth.

Modalità sviluppo e revisione

Una nuova app parte in modalità sviluppo. Funziona subito, ma solo il tuo account Gravl può autorizzarla: gli altri utenti vedono un avviso nella schermata di consenso e non possono collegarsi. Usala per costruire e testare l'intero flusso.

• Quando la tua app è pronta, clicca su Invia per la revisione. Controlliamo nome, descrizione, logo, homepage, redirect URI e scope, e ti comunichiamo la decisione via email
• Dopo l'approvazione, qualsiasi utente Gravl può collegare la tua app
• Se la rifiutiamo, l'email e la pagina delle impostazioni mostrano il motivo: modifica l'app e inviala di nuovo
• Le app approvate non si possono modificare dalla pagina delle impostazioni, logo compreso

Per modificare un'app approvata, o per qualsiasi domanda su registrazione e revisione, scrivi a developers@gravl.ai.

2. Manda l'utente alla schermata di consenso

https://api.gravl.ai/oauth/authorize
  ?client_id=gci_…
  &redirect_uri=https://yourapp.example/callback   // must be registered exactly
  &scope=workouts:read stats:read                  // omit for all allowed scopes
  &state=<random value you verify on return>
  &code_challenge=<S256(code_verifier)>
  &code_challenge_method=S256

L'utente accede con il suo account Gravl, vede il nome della tua app e gli scope richiesti in linguaggio chiaro e approva: il suo browser torna alla tua redirect_uri con ?code=gac_…&state=… (oppure error=access_denied se annulla).

• I codici hanno prefisso gac_, valgono 10 minuti, sono monouso e sono legati alla tua app e alla redirect_uri per cui sono stati emessi
• PKCE (S256) è obbligatorio per i client pubblici (app browser o native, che non hanno un client_secret) e fortemente consigliato per tutti
• Verifica sempre che state corrisponda a quello che hai inviato: è la tua protezione CSRF

I client pubblici omettono client_secret all'endpoint dei token: PKCE è la loro autenticazione client. Scegli il tipo di client quando crei l'app.

3. Scambia il codice

curl -X POST https://api.gravl.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=gac_… \
  -d client_id=gci_… \
  -d client_secret=gcs_… \
  -d code_verifier=<your PKCE verifier> \
  -d redirect_uri=https://yourapp.example/callback

{
  "access_token": "gat_…",
  "token_type": "Bearer",
  "expires_in": 21600,
  "refresh_token": "grt_…",
  "scope": "workouts:read stats:read"
}

4. Rinnova

curl -X POST https://api.gravl.ai/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=grt_… \
  -d client_id=gci_… \
  -d client_secret=gcs_…

La risposta ha la stessa forma dello scambio del codice. Il refresh token presentato viene revocato nella stessa transazione: salva sempre il nuovo refresh_token prima di scartare il vecchio. Riutilizzare un refresh token già usato restituisce invalid_grant.

5. Revoca

curl -X POST https://api.gravl.ai/oauth/revoke \
  -d token=grt_… \
  -d client_id=gci_… \
  -d client_secret=gcs_…

• Revocare un access token elimina solo quel token
• Revocare un refresh token revoca l'intero grant: ogni token in circolazione per quella coppia utente + app
• Come da RFC 7009 l'endpoint restituisce 200 anche per token sconosciuti: solo credenziali client errate producono un errore
• Gli utenti possono anche revocare l'accesso della tua app dal loro account

Errori dell'endpoint dei token

Gli errori seguono la RFC 6749: { "error": "…", "error_description": "…" }