Inicio rápido de OAuth 2.0 para aplicaciones conectadas a Cathopic - Centro de Ayuda

Las aplicaciones conectadas de Cathopic usan OAuth 2.0 Authorization Code con PKCE S256 obligatorio. La misma aprobación de desarrollador también habilita la API comercial de Cathopic, pero las conexiones OAuth usan tokens de usuario y el plan del usuario conectado en lugar de API keys y facturación por uso de la API.

1. Obtén acceso y registra la aplicación

Envía la única solicitud de acceso de desarrollador desde el formulario de contacto. Cuando Cathopic apruebe la cuenta por email, abre Ajustes → Developer / API → Aplicaciones OAuth, crea la aplicación, registra sus callbacks exactos y scopes necesarios, y guarda el secreto de un solo uso si es confidencial.

2. Descubre el servidor de autorización

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

3. Redirige al usuario

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

Construye una sola URL; los saltos de línea solo facilitan la lectura. Genera valores nuevos y de alta entropía para state y PKCE en cada intento. ui_locales es opcional y permite pedir un idioma compatible, como es o en. Si hace falta iniciar sesión, Cathopic recupera la misma solicitud de autorización y muestra después la pantalla de permisos.

4. Valida el callback e intercambia el código

Compara el state recibido antes de intercambiar el código. El callback debe coincidir byte a 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=CALLBACK_EXACTO&code=CODIGO&code_verifier=VERIFICADOR

Las aplicaciones públicas omiten client_secret. Guarda los tokens y secretos confidenciales solo en el servidor y cifrados. Los access tokens duran 30 minutos; los refresh tokens duran hasta 30 días y rotan al usarse.

Comprobaciones habituales

Un callback rechazado suele diferir del registrado en esquema, host, puerto, path, mayúsculas o barra final.
invalid_request antes del consentimiento indica que falta PKCE S256, el challenge o state, o que su formato no es válido.
invalid_grant suele indicar que se reutilizó un código o refresh token rotado, o que cambiaron el callback o el verifier.
Tras un 401, refresca una vez; si falla, pide al usuario que vuelva a conectar. Un 403 indica que falta el scope necesario.

Consulta el contrato OpenAPI completo y la guía detallada de integración de aplicaciones conectadas.