Guida rapida OAuth 2.0 per le app connesse Cathopic - Centro assistenza

Le App Connesse Cathopic usano OAuth 2.0 Authorization Code con PKCE S256 obbligatorio. La stessa approvazione dello sviluppatore sblocca anche la API commerciale di Cathopic, ma le connessioni OAuth usano i token dell’utente e il piano dell’utente connesso, invece delle chiavi API e della fatturazione a consumo della API.

1. Ottenere accesso e registrare l’applicazione

Invia la singola richiesta di accesso per sviluppatori tramite il modulo di contatto. Dopo che Cathopic approva l’account via email, apri Impostazioni → Developer / API → applicazioni OAuth, crea l’applicazione, registra i suoi callback esatti e gli scope richiesti, e salva il suo segreto una tantum se è riservata.

2. Scoprire il server di autorizzazione

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

3. Reindirizzare l’utente

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

Costruisci un singolo URL; gli a capo servono solo a rendere l’esempio leggibile. Genera nuovi valori di state ad alta entropia e PKCE per ogni tentativo. ui_locales è opzionale e può richiedere una lingua supportata come en oppure es. Se è richiesto l’accesso, Cathopic riprende la stessa richiesta di autorizzazione e poi mostra la schermata delle autorizzazioni.

4. Validare il callback e scambiare il codice

Confronta lo state restituito prima di scambiare il codice. L’URI di reindirizzamento deve corrispondere byte per byte.

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

Le applicazioni pubbliche omettono client_secret. Salva i token e i segreti riservati solo sul server e crittografali a riposo. I token di accesso durano 30 minuti; i token di refresh durano fino a 30 giorni e vengono ruotati quando vengono usati.

Controlli comuni

Un callback rifiutato di solito differisce dall’URI registrato per schema, host, porta, percorso, maiuscole/minuscole o barra finale.
invalid_request prima del consenso significa che PKCE S256, la challenge o lo state sono mancanti o non validi.
invalid_grant di solito significa che un codice o un token di refresh ruotato è stato riutilizzato, oppure che il callback o il verifier sono cambiati.
Dopo un 401, aggiorna una volta; se l’aggiornamento fallisce, chiedi all’utente di riconnettersi. Un 403 significa che il token non dispone dello scope richiesto.

Vedi il contratto OpenAPI completo e la guida dettagliata all’integrazione delle Connected Apps.