Aplikacje OAuth

1. Zarejestruj aplikację

Aplikację rejestrujesz samodzielnie. Zaloguj się na swoje konto Gravl na app.gravl.ai/settings/developer i otwórz sekcję Aplikacje OAuth, obok Twoich osobistych tokenów dostępu.

Podajesz tam:

• Nazwę aplikacji i krótki opis tego, co robi; nazwa nie może zawierać „Gravl”
• Opcjonalne logo: kwadratowy plik PNG, JPEG lub WebP (bez SVG), co najmniej 128×128 px i maksymalnie 1 MB. Wyświetla się na ekranie zgody obok nazwy aplikacji
• Stronę główną aplikacji: adres https
• Do 5 adresów redirect URI: bezwzględne adresy https (http://localhost dozwolony na czas developmentu)
• Scope’y, których potrzebuje Twoja aplikacja. Proś o minimum; użytkownicy widzą dokładnie to, o co prosisz
• Typ klienta: poufny (confidential) dla aplikacji serwerowych, które mogą bezpiecznie przechowywać client_secret, albo publiczny (public) dla aplikacji przeglądarkowych i natywnych, które nie dostają sekretu i muszą używać PKCE

Od razu dostajesz client_id (gci_…). Klienci poufni dostają też client_secret (gcs_…, pokazywany tylko raz; przechowuj go jak hasło). Później możesz wymienić sekret na nowy na tej samej stronie. Jedno konto może mieć do 5 aplikacji OAuth.

Tryb deweloperski i weryfikacja

Nowa aplikacja startuje w trybie deweloperskim. Działa od razu, ale autoryzować ją może tylko Twoje własne konto Gravl. Inni użytkownicy widzą komunikat na ekranie zgody i nie mogą się połączyć. Wykorzystaj ten tryb, aby zbudować i przetestować cały przepływ.

• Gdy aplikacja jest gotowa, kliknij Wyślij do weryfikacji. Sprawdzamy nazwę, opis, logo, stronę główną, adresy redirect URI i scope’y, a decyzję wysyłamy e-mailem
• Po zatwierdzeniu każdy użytkownik Gravl może połączyć Twoją aplikację
• Jeśli ją odrzucimy, powód znajdziesz w e-mailu i na stronie ustawień; popraw aplikację i prześlij ją ponownie
• Zatwierdzonych aplikacji nie można edytować na stronie ustawień (dotyczy to też logo)

Aby zmienić zatwierdzoną aplikację lub zadać pytanie o rejestrację albo weryfikację, napisz na developers@gravl.ai.

2. Wyślij użytkownika na ekran zgody

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żytkownik loguje się na swoje konto Gravl, widzi nazwę Twojej aplikacji i żądane scope’y opisane prostym językiem, po czym zatwierdza. Jego przeglądarka wraca na Twój redirect_uri z ?code=gac_…&state=… (lub z error=access_denied, jeśli anuluje).

• Kody mają prefiks gac_, są ważne 10 minut, jednorazowe i powiązane z Twoją aplikacją oraz z redirect_uri, dla którego zostały wydane
• PKCE (S256) jest wymagane dla klientów publicznych (aplikacje przeglądarkowe lub natywne, które nie mają client_secret) i mocno zalecane wszystkim
• Zawsze weryfikuj, że state zgadza się z tym, co wysłano. To Twoja ochrona przed CSRF

Klienci publiczni pomijają client_secret na endpoincie tokenów; ich uwierzytelnieniem klienta jest PKCE. Typ klienta wybierasz przy tworzeniu aplikacji.

3. Wymień kod

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. Odśwież

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

Odpowiedź ma ten sam kształt co wymiana kodu. Przedstawiony token odświeżania jest unieważniany w tej samej transakcji, więc zawsze zapisz nowy refresh_token, zanim odrzucisz stary. Ponowne użycie zużytego tokena odświeżania zwraca invalid_grant.

5. Unieważnij

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

• Unieważnienie tokena dostępu ubija tylko ten token
• Unieważnienie tokena odświeżania unieważnia cały grant: każdy aktywny token dla tej pary użytkownik + aplikacja
• Zgodnie z RFC 7009 endpoint zwraca 200 nawet dla nieznanych tokenów. Błąd powodują tylko złe poświadczenia klienta
• Użytkownicy mogą też odebrać Twojej aplikacji dostęp z poziomu swojego konta

Błędy endpointu tokenów

Błędy są zgodne z RFC 6749: { "error": "…", "error_description": "…" }: