Szybki start OAuth 2.0 dla połączonych aplikacji Cathopic - Centrum pomocy

Połączone aplikacje Cathopic korzystają z OAuth 2.0 Authorization Code z obowiązkowym PKCE S256. To samo zatwierdzenie programisty odblokowuje również komercyjny API Cathopic, ale połączenia OAuth używają tokenów użytkownika i planu połączonego użytkownika zamiast kluczy API oraz rozliczeń naliczanych za użycie API.

1. Uzyskaj dostęp i zarejestruj aplikację

Złóż pojedynczy wniosek o dostęp programisty przez formularz kontaktowy. Po tym, jak Cathopic zatwierdzi konto e-mailem, otwórz Ustawienia → Developer / API → OAuth applications, utwórz aplikację, zarejestruj jej dokładne callbacki oraz wymagane zakresy (scopes), a jeśli jest poufna, zapisz jej jednorazowy sekret.

2. Odkryj serwer autoryzacji

GET https://cathopic.com/.well-known/oauth-authorization-server

3. Przekieruj użytkownika

GET https://cathopic.com/oauth/authorize
    ?client_id=CLIENT_ID
    &redirect_uri=EXACT_CALLBACK
    &response_type=code
    &scope=account.read%20catalog.read%20entitlements.read%20licenses.create%20licenses.read
    &state=UNGUESSABLE_STATE
    &code_challenge=BASE64URL_SHA256_VERIFIER
    &code_challenge_method=S256
    &ui_locales=en

Zbuduj jeden adres URL; podziały linii służą tylko temu, aby przykład był czytelny. Za każdym razem wygeneruj nowy stan o wysokiej entropii oraz wartości PKCE. ui_locales jest opcjonalne i może prosić o obsługiwany język, taki jak en lub es. Jeśli wymagane jest logowanie, Cathopic wznawia ten sam wniosek o autoryzację, a następnie wyświetla ekran uprawnień.

4. Zweryfikuj callback i wymień kod

Porównaj zwrócony stan przed wymianą kodu. Adres URI przekierowania musi być zgodny bajt w bajt.

POST https://cathopic.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=EXACT_CALLBACK&code=CODE&code_verifier=VERIFIER

Aplikacje publiczne pomijają client_secret. Tokeny i poufne sekrety przechowuj wyłącznie na serwerze oraz szyfruj je w spoczynku. Tokeny dostępu wygasają po 30 minutach; tokeny odświeżania wygasają maksymalnie po 30 dniach i są rotowane po użyciu.

Typowe sprawdzenia

Odrzucony callback zwykle różni się od zarejestrowanego URI schematem, hostem, portem, ścieżką, wielkością liter lub ukośnikiem na końcu.
invalid_request przed consent oznacza, że brakuje PKCE S256, challenge lub state albo są nieprawidłowe.
invalid_grant zwykle oznacza, że kod lub zrotowany token odświeżania został ponownie użyty albo zmienił się callback lub verifier.
Po 401 odśwież raz; jeśli odświeżanie się nie powiedzie, poproś użytkownika o ponowne połączenie. 403 oznacza, że token nie ma wymaganego zakresu.

Zobacz kompletne kontrakt OpenAPI oraz szczegółowy przewodnik integracji Connected Apps.