Apps OAuth

1. Enregistre ton app

Tu enregistres ton app toi-même. Connecte-toi avec ton compte Gravl sur app.gravl.ai/settings/developer et ouvre la section Apps OAuth, à côté de tes tokens d’accès personnels.

Tu y renseignes :

• Le nom de ton app et une courte description de ce qu’elle fait ; le nom ne peut pas contenir « Gravl »
• Un logo facultatif : un PNG, JPEG ou WebP carré (pas de SVG), d’au moins 128×128 px et de 1 Mo maximum. Il apparaît sur l’écran de consentement à côté du nom de ton app
• La page d’accueil de ton app : une URL https
• Jusqu’à 5 redirect URI : des URLs https absolues (http://localhost autorisé pour le développement)
• Les scopes dont ton app a besoin : demande le minimum ; les utilisateurs voient exactement ce que tu demandes
• Le type de client : confidentiel pour les apps côté serveur qui peuvent garder un client_secret, ou public pour les apps navigateur et natives, qui n’ont pas de secret et doivent utiliser PKCE

Tu reçois immédiatement un client_id (gci_…). Les clients confidentiels reçoivent aussi un client_secret (gcs_…, affiché une seule fois : stocke-le comme un mot de passe). Tu peux renouveler le secret plus tard depuis la même page. Chaque compte peut avoir jusqu’à 5 apps OAuth.

Mode développement et validation

Une nouvelle app démarre en mode développement. Elle fonctionne tout de suite, mais seul ton propre compte Gravl peut l’autoriser : les autres utilisateurs voient un avertissement sur l’écran de consentement et ne peuvent pas se connecter. Profites-en pour construire et tester tout le flow.

• Quand ton app est prête, clique sur Soumettre pour examen. Nous vérifions le nom, la description, le logo, la page d’accueil, les redirect URI et les scopes, puis nous t’envoyons la décision par e-mail
• Une fois l’app approuvée, n’importe quel utilisateur Gravl peut la connecter
• Si nous la refusons, l’e-mail et la page de réglages indiquent la raison : modifie l’app et soumets-la à nouveau
• Les apps approuvées ne peuvent plus être modifiées depuis la page de réglages, logo compris

Pour modifier une app approuvée, ou pour toute question sur l’enregistrement ou la validation, écris à developers@gravl.ai.

2. Envoie l’utilisateur vers l’écran de consentement

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’utilisateur se connecte avec son compte Gravl, voit le nom de ton app et les scopes demandés en langage clair, puis approuve : son navigateur revient sur ta redirect_uri avec ?code=gac_…&state=… (ou error=access_denied s’il annule).

• Les codes sont préfixés gac_, valables 10 minutes, à usage unique, et liés à ton app et à la redirect_uri pour laquelle ils ont été émis
• PKCE (S256) est requis pour les clients publics (apps navigateur ou natives, qui n’ont pas de client_secret) et fortement recommandé pour tout le monde
• Vérifie toujours que state correspond à ce que tu as envoyé : c’est ta protection CSRF

Les clients publics omettent client_secret sur l’endpoint de token : PKCE fait office d’authentification client. Tu choisis le type de client en créant l’app.

3. Échange le code

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. Rafraîchir

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 réponse a la même forme que l’échange de code. Le refresh token présenté est révoqué dans la même transaction : persiste toujours le nouveau refresh_token avant de jeter l’ancien. Rejouer un refresh token déjà utilisé renvoie invalid_grant.

5. Révoquer

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

• Révoquer un access token ne tue que ce token
• Révoquer un refresh token révoque l’autorisation entière : tous les tokens en circulation pour ce couple utilisateur + app
• Conformément à la RFC 7009, l’endpoint renvoie 200 même pour un token inconnu : seuls de mauvais identifiants client produisent une erreur
• Les utilisateurs peuvent aussi révoquer l’accès de ton app depuis leur compte

Erreurs de l’endpoint de token

Les erreurs suivent la RFC 6749, au format { "error": "…", "error_description": "…" }: