OAuth aplikace

1. Zaregistruj svoji aplikaci

Dokud je API v betě, probíhá registrace ručně. Napiš na developers@gravl.ai a uveď:

• Název své aplikace a krátký popis, co dělá
• Svoje OAuth redirect URI, tedy absolutní https URL (http://localhost je povolen pro vývoj)
• Jaké scopes tvoje aplikace potřebuje; žádej minimum, uživatelé vidí přesně to, o co si řekneš

Dostaneš client_id (gci_…) a client_secret (gcs_…, zobrazí se jen jednou, ulož ho jako heslo).

2. Pošli uživatele na obrazovku souhlasu

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

Uživatel se přihlásí svým účtem Gravl, srozumitelně uvidí název tvé aplikace i požadované scopes a potvrdí je. Jeho prohlížeč se pak vrátí na tvůj redirect_uri s ?code=gac_…&state=… (nebo s error=access_denied, pokud to zruší).

• Kódy mají prefix gac_, platí 10 minut, jsou na jedno použití a jsou vázané na tvoji aplikaci a redirect_uri, pro který byly vydány
• PKCE (S256) je povinné pro public klienty (prohlížečové nebo nativní aplikace, které nemají client_secret) a důrazně doporučené pro všechny
• Vždy ověř, že state odpovídá tomu, co jsi poslal; je to tvoje ochrana proti CSRF

Public klienti na token endpointu client_secret vynechávají, jejich klientskou autentizací je PKCE. Při registraci nám napiš, kterého typu tvoje aplikace je.

3. Vyměň kód

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. Refresh

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_…

Response má stejný tvar jako výměna kódu. Předložený refresh token se zneplatní ve stejné transakci; nový refresh_token si vždy ulož dřív, než zahodíš ten starý. Opakované použití už spotřebovaného refresh tokenu vrací invalid_grant.

5. Zneplatnění

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

• Zneplatnění access tokenu zabije jen ten jeden token
• Zneplatnění refresh tokenu odvolá celý grant, tedy všechny platné tokeny pro danou dvojici uživatel + aplikace
• Podle RFC 7009 vrací endpoint 200 i pro neznámé tokeny; chybu vyvolají jen špatné client credentials
• Uživatelé můžou přístup tvé aplikace odvolat i ze svého účtu

Chyby token endpointu

Chyby se řídí RFC 6749, tedy { "error": "…", "error_description": "…" }: