OAuth 2.0-Schnellstart für Cathopic verbundene Apps - Hilfecenter

Cathopic Connected Apps verwenden OAuth 2.0 Authorization Code mit obligatorischem PKCE S256. Die gleiche Entwicklerfreigabe schaltet auch die kommerzielle API von Cathopic frei, aber OAuth-Verbindungen nutzen Benutzertokens und den Tarif des verbundenen Benutzers anstelle von API-Schlüsseln und nutzungsabhängiger API-Abrechnung.

1. Zugriff erhalten und die Anwendung registrieren

Senden Sie die einzelne Entwicklerzugriffsanfrage über das Kontaktformular. Nachdem Cathopic das Konto per E-Mail genehmigt hat, öffnen Einstellungen → Entwickler / API → OAuth-Anwendungen, erstellen Sie die Anwendung, registrieren Sie ihre exakten Callbacks und erforderlichen Scopes und speichern Sie ihr einmaliges Geheimnis, falls sie vertraulich ist.

2. Den Autorisierungsserver ermitteln

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

3. Den Benutzer umleiten

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

Erstellen Sie eine einzige URL; die Zeilenumbrüche dienen nur dazu, das Beispiel lesbar zu machen. Generieren Sie bei jedem Versuch neuen State mit hoher Entropie und neue PKCE-Werte. ui_locales ist optional und kann eine unterstützte Sprache anfordern, wie z. B. en oder es. Wenn eine Anmeldung erforderlich ist, setzt Cathopic die gleiche Autorisierungsanfrage fort und zeigt dann den Berechtigungsbildschirm an.

4. Den Callback validieren und den Code austauschen

Vergleichen Sie den zurückgegebenen State, bevor Sie den Code austauschen. Die Redirect-URI muss bytegenau übereinstimmen.

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

Öffentliche Anwendungen lassen client_secretweg. Speichern Sie Tokens und vertrauliche Geheimnisse nur auf dem Server und verschlüsseln Sie sie im Ruhezustand. Zugriffstokens sind 30 Minuten gültig; Refresh-Tokens sind bis zu 30 Tage gültig und werden bei Verwendung rotiert.

Häufige Prüfungen

Ein abgelehnter Callback unterscheidet sich in der Regel von der registrierten URI durch Schema, Host, Port, Pfad, Groß-/Kleinschreibung oder einen abschließenden Schrägstrich.
invalid_request vor Zustimmung bedeutet, dass PKCE S256, die Challenge oder der State fehlt oder ungültig ist.
invalid_grant bedeutet üblicherweise, dass ein Code oder ein rotierter Refresh-Token wiederverwendet wurde oder dass sich der Callback oder der Verifier geändert hat.
Nach einem 401 einmal aktualisieren; wenn das Refresh fehlschlägt, bitten Sie den Benutzer, erneut zu verbinden. Ein 403 bedeutet, dass dem Token der erforderliche Scope fehlt.

Siehe die vollständige OpenAPI-Übereinkunft und die detaillierte Anleitung zur Integration Connected Apps.