OAuth aplikace

1. Zaregistruj svoji aplikaci

Aplikaci si zaregistruješ sám. Přihlas se svým účtem Gravl na app.gravl.ai/settings/developer a otevři sekci OAuth aplikace vedle svých osobních access tokenů.

Vyplníš tam:

• Název své aplikace a krátký popis, co dělá; název nesmí obsahovat „Gravl“
• Volitelně logo: čtvercové PNG, JPEG nebo WebP (SVG ne), alespoň 128×128 px a nejvýše 1 MB. Zobrazí se na obrazovce souhlasu vedle názvu aplikace
• Domovskou stránku aplikace, tedy https URL
• Až 5 redirect URI, tedy absolutních 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š
• Typ klienta: confidential pro serverové aplikace, které dokážou bezpečně uložit client_secret, nebo public pro prohlížečové a nativní aplikace, které žádný secret nedostanou a musí používat PKCE

Hned dostaneš client_id (gci_…). Confidential klienti dostanou i client_secret (gcs_…, zobrazí se jen jednou, ulož ho jako heslo). Secret můžeš později na stejné stránce vyměnit za nový. Jeden účet může mít až 5 OAuth aplikací.

Vývojový režim a schválení

Nová aplikace začíná ve vývojovém režimu. Funguje hned, ale autorizovat ji může jen tvůj vlastní účet Gravl. Ostatní uživatelé uvidí na obrazovce souhlasu upozornění a nepřipojí se. Celý flow si tak můžeš postavit a otestovat.

• Až bude aplikace hotová, klikni na Odeslat ke kontrole. Zkontrolujeme název, popis, logo, domovskou stránku, redirect URI a scopes a rozhodnutí ti pošleme e-mailem
• Po schválení může tvoji aplikaci připojit kterýkoli uživatel Gravl
• Pokud aplikaci zamítneme, najdeš důvod v e-mailu i na stránce nastavení; uprav aplikaci a odešli ji znovu
• Schválené aplikace už na stránce nastavení upravit nejde, a to ani jejich logo

Kvůli změnám ve schválené aplikaci nebo s dotazy k registraci a schválení napiš na developers@gravl.ai.

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. Typ klienta si vybereš při vytváření aplikace.

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": "…" }: