OAuth 2.0 quickstart voor Cathopic connected apps - Helpcentrum

Cathopic Connected Apps gebruiken OAuth 2.0 Authorization Code met verplichte PKCE S256. Dezelfde goedkeuring van de ontwikkelaar ontgrendelt ook de commerciële API van Cathopic, maar OAuth-verbindingen gebruiken gebruikers-tokens en het abonnement van de verbonden gebruiker in plaats van API-sleutels en facturering per gebruik van de API.

1. Verkrijg toegang en registreer de applicatie

Dien het enkele verzoek om ontwikkelaarstoegang in via de contactformulier. Nadat Cathopic het account per e-mail heeft goedgekeurd, opent u Instellingen → Developer / API → OAuth-applicaties, maak de applicatie aan, registreer de exacte callbacks en vereiste scopes, en bewaar het eenmalige geheim ervan als het een vertrouwelijke applicatie is.

2. Ontdek de autorisatieserver

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

3. Redirect de gebruiker

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

Bouw één URL; de regeleinden maken het voorbeeld alleen leesbaar. Genereer voor elke poging nieuwe waarden met hoge entropie voor state en PKCE. ui_locales is optioneel en kan een ondersteunde taal opvragen zoals en of es. Als aanmelden vereist is, hervat Cathopic dezelfde autorisatieaanvraag en toont vervolgens het toestemmingsscherm.

4. Valideer de callback en wissel de code om

Vergelijk de teruggestuurde state voordat u de code omwisselt. De redirect URI moet byte voor byte overeenkomen.

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

Publieke applicaties weglaten client_secret. Bewaar tokens en vertrouwelijke geheimen alleen op de server en versleutel ze tijdens opslag. Access tokens zijn 30 minuten geldig; refresh tokens zijn tot 30 dagen geldig en worden geroteerd wanneer ze worden gebruikt.

Veelvoorkomende controles

Een afgewezen callback verschilt meestal van de geregistreerde URI door scheme, host, poort, pad, hoofdlettergebruik of een afsluitende slash.
invalid_request voor toestemming betekent dat PKCE S256, de challenge of state ontbreekt of ongeldig is.
invalid_grant betekent doorgaans dat een code of een geroteerde refresh token opnieuw is gebruikt, of dat de callback of verifier is gewijzigd.
Na een 401: vernieu w één keer; als vernieuwen mislukt, vraag de gebruiker dan om opnieuw te verbinden. Een 403 betekent dat de token niet over de vereiste scope beschikt.

Zie het volledige OpenAPI-contract en de gedetailleerde handleiding voor de integratie van Connected Apps.