Auth API

Última actualización: 3 de julio de 2026

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 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).

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). La estructura y los campos son hechos verificados con el código del servidor.

{
  "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"
}
CampoTipoDescripción
accessTokenstringToken Bearer usado en las llamadas a ACMA y ACDA.
tokenTypestringTipo de token. Siempre "Bearer".
scopearray de stringÁmbito de permisos del token. El token de ServiceUser es ["APP"].
createdAtstring (date-time)Momento de emisión del token.
expiresAtstring (date-time)Momento de expiración del accessToken.
refreshTokenstringToken usado para renovar el accessToken.
refreshExpiresAtstring (date-time)Momento de expiración del refreshToken. Tres días después de createdAt.

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 depende de la configuración del servidor, y el momento exacto de expiración se incluye en el campo expiresAt de la respuesta. 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).