Iniciar sesión con AcademyOS

Cómo encaja todo

Con la API de partners tú actúas como tú mismo: una clave a nivel de organización lista tu catálogo licenciado y concede acceso a tus clientes. Iniciar sesión con AcademyOS es la dirección opuesta: un alumno de AcademyOS inicia sesión en tu sitio y autoriza que leas su identidad — y, con un alcance adicional, los cursos del marketplace que tiene. Nunca ves su contraseña; puede revocarte en cualquier momento; cada token que tienes está limitado exactamente a lo que aceptó.

Es OAuth 2.0 authorization code + PKCE estándar con OpenID Connect encima (discovery, id_tokens RS256, JWKS, userinfo). Cualquier biblioteca cliente OIDC funciona: apúntala al documento de discovery y ya tienes la mayor parte hecha.

Registro

Registra tu organización partner en el portal de desarrolladores — basta una cuenta de AcademyOS con el e-mail confirmado — y crea allí tu cliente. Los clientes funcionan de inmediato; cada uso pasa por el consentimiento del alumno. La licencia de catálogo para la clave de la API de partners es una decisión comercial aparte que solicitas desde la misma página. Necesitarás:

• Tus URI de redirección — coincidencia exacta, https obligatorio fuera de desarrollo (se aceptan IPs de loopback como http://127.0.0.1:4567/callback para pruebas locales).
• Si tu cliente es confidencial (puedes guardar un secreto en el servidor: una app web clásica) o público (SPA o app móvil; sin secreto, PKCE aporta la prueba). El tipo de cliente no puede cambiarse después — otro tipo es otro cliente.
• Opcionalmente, un conjunto de alcances más reducido que los cuatro por defecto (ver Alcances).
• El nombre que se mostrará en la pantalla de consentimiento y un e-mail de contacto técnico.

Recibes un client_id y, para clientes confidenciales, un client_secret que se muestra exactamente una vez, al crearlo — solo guardamos su digest SHA-256, igual que con las claves de la API de partners. Un secreto perdido se rota, no se recupera; la rotación muestra un secreto nuevo una vez e invalida el anterior de inmediato.

Un partner puede tener varios clientes (uno por plataforma). Todos tus clientes, tokens y consentimientos mueren en el momento en que se desactiva tu cuenta de partner — el mismo interruptor de apagado que tus claves de API.

Registrar tu aplicación

Endpoints

CORS está abierto deliberadamente solo en los endpoints públicos sin cookies que un cliente PKCE en el navegador debe llamar; todo lo demás conserva el comportamiento same-origin del navegador. /oauth/authorize es un destino de redirección, no una API — no hagas fetch de él.

Alcances (scopes)

Fíjate en los dos puntos de enrollments:read. Los alcances desconocidos se rechazan con el error estándar invalid_scope, y una configuración por cliente puede reducir aún más esta lista. Pide el conjunto más pequeño que necesites: la pantalla de consentimiento muestra cada alcance al alumno, y pedir enrollments:read sin usarlo te cuesta confianza.

El flujo de autorización

Authorization code con PKCE (S256). PKCE es obligatorio — los clientes públicos no pueden completar el flujo sin él, y a los confidenciales que lo envían se les verifica. Sin implicit, sin password, sin client-credentials: un partner que actúa como él mismo usa su clave de la API de partners, no OAuth.

1. Redirige al alumno (navegación de nivel superior) a:

   GET https://app.academyos.app/oauth/authorize?client_id=…&redirect_uri=…&response_type=code
       &scope=openid+email+enrollments:read
       &state=<aleatorio>&nonce=<aleatorio>
       &code_challenge=<S256(code_verifier)>&code_challenge_method=S256

2. El alumno inicia sesión en AcademyOS si aún no lo ha hecho — incluido su paso de 2FA — y vuelve automáticamente a la pantalla de consentimiento. La pantalla nombra tu app y tu organización partner y lista los alcances. Aprueba o deniega.

3. La aprobación redirige a tu redirect_uri con ?code=…&state=…. El code es de un solo uso y vive 10 minutos.

4. Intercámbialo (en el servidor, o desde la SPA — el endpoint tiene CORS abierto):

   POST https://app.academyos.app/oauth/token
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=authorization_code&code=…&redirect_uri=…
   &client_id=…&code_verifier=…
   [&client_secret=… para clientes confidenciales]

   {
     "access_token": "…", "token_type": "Bearer", "expires_in": 7200,
     "refresh_token": "…", "scope": "openid email enrollments:read",
     "created_at": 1724751600, "id_token": "eyJhbGciOiJSUzI1NiIs…"
   }

Los clientes confidenciales pueden autenticarse en el endpoint de token con HTTP Basic (client_secret_basic) o con parámetros de formulario (client_secret_post); se aceptan ambos.

Ciclo de vida de los tokens

El refresh rota con una ventana de traspaso: intercambiar un refresh token devuelve un nuevo par access + refresh, y el par al que sustituye sigue siendo válido hasta que el nuevo access token se usa por primera vez — una respuesta de token perdida en la red no puede dejarte fuera, porque reintentar el intercambio con el refresh token antiguo sigue funcionando hasta entonces. Desde el primer uso del nuevo access token, el par sustituido queda revocado y reutilizar su refresh token se rechaza (invalid_grant). Guarda siempre el par más nuevo.

POST https://app.academyos.app/oauth/token
grant_type=refresh_token&refresh_token=…&client_id=…[&client_secret=…]

Revoca los tokens que ya no necesites (cierre de sesión, desvinculación de cuenta) según RFC 7009:

POST https://app.academyos.app/oauth/revoke
token=…&client_id=…[&client_secret=…]

Los tokens se guardan como digests SHA-256, como cualquier otra credencial que guardamos por ti.

La API de recursos

Authorization: Bearer <access_token> contra /api/oauth/v1. Es un tercer régimen de credenciales: aquí no se aceptan claves de la API de partners ni tokens de la app móvil de AcademyOS, y los tokens OAuth no se aceptan en la API de partners ni en la API móvil. Los errores tienen la forma habitual:

{ "sub": "user_9tRk…", "email": "learner@example.com", "email_verified": true, "name": "Ada Learner" }

{
  "marketplace_enrollments": [
    {
      "kind": "purchase",
      "order_id": "mord_…", "order_status": "paid",
      "purchased_at": "2026-08-11T14:03:22Z", "granted_at": null,
      "product_id": "prod_…", "name": "Practical Math", "slug": "practical-math",
      "creator_name": "Creator One Studio", "cover_image_url": "https://…",
      "access_state": "active", "access_expires_at": "2026-09-10T14:03:22Z",
      "days_remaining": 14, "enrollment_status": "active"
    },
    {
      "kind": "grant",
      "order_id": null, "order_status": null,
      "purchased_at": null, "granted_at": "2026-08-12T09:00:00Z",
      "product_id": "prod_…", "name": "…", "slug": "…",
      "creator_name": "…", "cover_image_url": "https://…",
      "access_state": "active", "access_expires_at": null,
      "days_remaining": null, "enrollment_status": "active"
    }
  ]
}

Qué ve y controla el alumno

• La pantalla de consentimiento lleva la marca, está localizada (en/es/pt) y nombra tanto tu aplicación como tu organización partner.
• Los alumnos revisan todas las apps que han autorizado en Configuración → Apps autorizadas, y pueden revocar cualquiera en cualquier momento. La revocación mata todos tus tokens de ese alumno a la vez; el siguiente authorize parte de una pantalla de consentimiento nueva. Diseña para que los tokens puedan morir en cualquier momento — el 401 te dice que vuelvas a autorizar.
• Un administrador de AcademyOS que suplanta a un alumno no puede dar consentimiento en su nombre; el flujo lo rechaza.

Interruptor de apagado, límites y letra pequeña

• La desactivación del partner es total: authorize muestra la página de error OAuth estándar, el endpoint de token responde invalid_client, y todos los access/refresh tokens ya emitidos responden 401 invalid_token desde ese mismo instante. La reactivación restaura los tokens que no hayan caducado.
• /oauth/authorize tiene límite por IP (30/min por defecto), /oauth/token por IP (60/min por defecto); 429 con cuerpo de texto plano. Acotan el credential stuffing, no tu tráfico legítimo.
• Las URI de redirección son de coincidencia exacta y solo https fuera de desarrollo, salvo callbacks a IPs de loopback (http://127.0.0.1:<puerto>/…), cuyo puerto puede variar en el authorize según RFC 8252. Sin comodines, sin fragmentos.
• El endpoint authorize debe ser una navegación de nivel superior — depende de la cookie de sesión de AcademyOS del alumno, que no existe en contextos cross-site de iframe o fetch.
• No hay endpoint de introspección de tokens; la identidad viene del id_token y de userinfo.

Checklist de integración

1. Registra tu organización y tu cliente en el portal de desarrolladores; guarda el client_id (y el client_secret de un solo vistazo, si es confidencial) en tu gestor de secretos.
2. Apunta una biblioteca cliente OIDC a https://app.academyos.app/.well-known/openid-configuration.
3. Envía a los alumnos por authorize con PKCE + state + nonce; valida todo a la vuelta.
4. Indexa tus cuentas por sub. Trata email como dato de presentación salvo que email_verified sea true.
5. Pide enrollments:read solo si realmente muestras los cursos del alumno.
6. Refresca de forma proactiva (los access tokens viven 2 horas), guarda el par rotado y trata cualquier 401 como "enviar al alumno por authorize otra vez".
7. Revoca los tokens al cerrar sesión o desvincular en lugar de dejar que caduquen.

Ejecutar el cliente de ejemplo

El repositorio de AcademyOS incluye un cliente de referencia sin framework en examples/oauth-client/app.rb que recorre toda esta página en un navegador real: discovery, PKCE, el callback, el intercambio del code como cliente confidencial, la verificación del id_token contra el JWKS, las tres llamadas de recursos, la rotación de refresh y la revocación. Cada página que renderiza imprime las respuestas crudas del servidor, así que también sirve como herramienta de depuración para tu propia integración.

cp .env.example .env   # ACADEMYOS_ISSUER, CLIENT_ID, CLIENT_SECRET, REDIRECT_URI, SESSION_SECRET
ruby app.rb            # luego abre http://localhost:4567 y pulsa "Sign in with AcademyOS"

Contra un AcademyOS desplegado la URI de redirección debe ser https (o una IP de loopback): pon el cliente detrás de un túnel como cloudflared tunnel --url http://localhost:4567 y registra la URL de callback del túnel. El README junto al script incluye el checklist de evidencias que ejecutamos nosotros mismos.