Auth API

Auth API es el flujo OAuth que autentica a un ServiceUser (el suscriptor general de un producto operado por un Space) mediante inicio de sesión social. Al iniciar sesión con el proveedor vinculado a la configuración de ServiceLogin (por ejemplo, Google), esta API emite un accessToken y un refreshToken. El accessToken emitido es un token Bearer que solo se usa en llamadas a ACMA y ACDA; no puede usarse en CMA ni CDA. Ningún token cruza los límites de identidad.

La URL base es https://auth.weegloo.com/v1 y todas las rutas están bajo /spaces/{spaceId}/.... Todos los cuerpos de petición y respuesta son JSON. Si se trata de una aplicación de navegador, se recomienda usar el SDK oficial weegloo-service-user en lugar de manejar directamente este protocolo. Esta página describe el protocolo HTTP que ese SDK llama internamente. Consúltela cuando implemente el flujo directamente en entornos donde no se puede usar el SDK (servidores, nativos, scripts).

Flujo de inicio de sesión

El flujo de inicio de sesión que se describe a continuación corresponde a las aplicaciones de navegador web. Las aplicaciones nativas (Android e iOS) manejan el callback de forma distinta, por lo que se tratan por separado en Callback de la app nativa.

El inicio de sesión se realiza en cuatro pasos.

1. Dirija el navegador a la URL de entrada de inicio de sesión (/spaces/{spaceId}/login/oauth2/{provider}). Esta URL inicia la cadena de redirecciones que conduce a la pantalla de inicio de sesión del proveedor (Google).
2. Cuando el inicio de sesión finaliza, Weegloo devuelve el navegador al callbackUrl configurado en ServiceLogin y añade ?exchangeToken=<token de un solo uso> a la dirección.
3. La página de callback lee el exchangeToken de la dirección y lo envía al endpoint de intercambio de tokens (POST /spaces/{spaceId}/oauth/token), recibiendo en la respuesta un accessToken y un refreshToken.
4. A continuación, llame a ACMA y ACDA usando el accessToken como token Bearer. Renueve con el refreshToken antes de la expiración (expiresAt) y descarte los tokens al cerrar sesión.

El exchangeToken es de un solo uso. Elimínelo de la barra de direcciones inmediatamente después de procesar el callback para evitar su exposición y reutilización (si usa el SDK, esto se gestiona automáticamente).

Callback de la app nativa: puente de deep link

Las aplicaciones nativas de Android e iOS también inician sesión con el mismo flujo OAuth. Sin embargo, en callbackUrl solo se puede indicar una dirección web, por lo que la forma de conectarlas es distinta.

El callbackUrl admitido según la documentación es una dirección web como https://.... Un esquema personalizado registrado por la app, como myapp://, se rechaza, por lo que no puede usarse directamente como dirección de callback. Por eso, en las aplicaciones nativas se define el callbackUrl como una página puente https alojada en Web Hosting, y esa página pasa el ?exchangeToken=... incluido en el callback al deep link de la app (por ejemplo, myapp://auth/callback?exchangeToken=...). La app realiza por sí misma el intercambio de tokens (el paso 3 del flujo de inicio de sesión de arriba, POST /spaces/{spaceId}/oauth/token) con ese exchangeToken.

• Por el deep link solo se pasa el exchangeToken de un solo uso. El accessToken y el refreshToken no viajan por el deep link, porque la app los obtiene mediante su propio intercambio. La página puente también elimina el exchangeToken de la dirección después de pasarlo (el mismo principio que el callback del flujo de inicio de sesión).
• Siempre que sea posible, use deep links verificados (Android App Links, iOS Universal Links). Un esquema personalizado sin verificar puede ser interceptado por otra app instalada en el dispositivo.
• El cliente OAuth del proveedor (por ejemplo, Google) se crea de tipo Web application aunque se trate de una app nativa. Esto se debe a que la redirección OAuth no va hacia la app, sino hacia auth.weegloo.com (una dirección web).

Cómo desplegar la página puente se trata en Web Hosting.

Modelo de tokens

El intercambio y la renovación de tokens devuelven una respuesta de token con la misma forma. Las cadenas de token y las marcas de tiempo incluidas en la respuesta son los valores de ejemplo de abajo; en realidad son cadenas secretas opacas (al tratarse de un flujo que pasa por el inicio de sesión del proveedor, no es posible reproducir los valores reales tal cual).

{
  "accessToken": "QY3xK9pR2mLs7Vc0Zt8Nf4Wd1Bj6Hg5Ua2Ee9Ck3PoZt8Nf4Wd",
  "tokenType": "Bearer",
  "scope": ["APP"],
  "createdAt": "2026-06-18T05:00:00.000Z",
  "expiresAt": "2026-06-19T05:00:00.000Z",
  "refreshToken": "Rf7Hn2Qw9Zx4Tp1Lk6Vc3Bm8Yd5Gs0Ae2Uj7Co4NeLk6Vc3Bm",
  "refreshExpiresAt": "2026-06-21T05:00:00.000Z"
}

Las duraciones de los tres tokens son las siguientes.

• El exchangeToken es de un solo uso y de vida corta. Debe intercambiarse de inmediato tras el callback. No se incluye en la respuesta de intercambio; se entrega en la dirección en el paso 2 del flujo de inicio de sesión.
• La duración del accessToken no es un valor fijo. El momento exacto de expiración se incluye en el campo expiresAt de la respuesta, así que decida a partir de ese valor. Es exclusivo de ACMA y ACDA.
• El refreshToken es válido durante tres días tras su emisión (refreshExpiresAt). Al invocar la renovación se emite un nuevo par de accessToken y refreshToken, y el par anterior se descarta (rotación). Cada vez que se renueva, el refreshToken inmediatamente anterior deja de poder usarse.

API

La URL base de los cuatro endpoints siguientes es siempre https://auth.weegloo.com/v1. Se tratan en este orden: entrada de inicio de sesión (GET), intercambio de tokens (POST), renovación de tokens (POST) y cierre de sesión (DELETE).

Documentos relacionados

• Inicio de sesión de ServiceUser (concepto): cómo configurar ServiceLogin en el estudio de contenidos.
• ACMA: API para gestionar el contenido de los miembros con el token emitido.
• ACDA: API de lectura que se entrega a los miembros.