Démarrage rapide OAuth 2.0 pour les applications connectées Cathopic

Les applications connectées Cathopic utilisent le flux OAuth 2.0 Authorization Code avec un PKCE S256 obligatoire. La même validation du développeur débloque également l’API commerciale de Cathopic, mais les connexions OAuth utilisent des jetons utilisateur et le plan de l’utilisateur connecté, plutôt que des clés d’API et une facturation API à l’usage.

1. Obtenir l’accès et enregistrer l’application

Soumettez la demande unique d’accès développeur via le formulaire de contact. Après que Cathopic a approuvé le compte par e-mail, ouvrez Paramètres → Développeur / API → Applications OAuth, créez l’application, enregistrez ses rappels (callbacks) exacts et les scopes requis, et stockez son secret à usage unique s’il est confidentiel.

2. Découvrir le serveur d’autorisation

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

3. Rediriger l’utilisateur

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

Construisez une seule URL ; les retours à la ligne ne servent qu’à rendre l’exemple lisible. Générez de nouvelles valeurs de state à haute entropie et de PKCE pour chaque tentative. ui_locales est optionnel et peut demander une langue prise en charge telle que en ou es. Si une connexion est requise, Cathopic reprend la même demande d’autorisation, puis affiche l’écran d’autorisation.

4. Valider le callback et échanger le code

Comparez le state renvoyé avant d’échanger le code. L’URI de redirection doit correspondre octet pour octet.

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

Les applications publiques omettent client_secret. Stockez les jetons et les secrets confidentiels uniquement sur le serveur et chiffrez-les au repos. Les jetons d’accès durent 30 minutes ; les jetons d’actualisation durent jusqu’à 30 jours et sont renouvelés (rotated) lorsqu’ils sont utilisés.

Contrôles courants

• Un callback rejeté diffère généralement de l’URI enregistrée par le schéma, l’hôte, le port, le chemin, la casse, ou la barre oblique finale.

• invalid_request avant consentement signifie que PKCE S256, le challenge ou le state est manquant ou invalide.

• invalid_grant signifie généralement qu’un code ou qu’un jeton d’actualisation renouvelé a été réutilisé, ou que le callback ou le vérificateur a changé.

• Après un 401, actualisez une fois ; si l’actualisation échoue, demandez à l’utilisateur de se reconnecter. Un 403 signifie que le jeton ne dispose pas du scope requis.

Consultez le contrat OpenAPI et le guide détaillé d’intégration des applications connectées.