Guía para desarrolladores de VU ONE FREE

Esta guía reúne lo que conviene saber antes de escribir la primera línea de código contra VU ONE: dónde vive la API de su tenant, qué flujo de OAuth corresponde a cada tipo de aplicación y qué convenciones comparten todos los endpoints. Si prefiere probar primero, siga el Inicio rápido y vuelva después.

VU ONE FREE es una versión limitada, en vista previa. Solo la usan las cuentas de Identity Link que VU seleccionó hasta la disponibilidad general. Algunas funciones son del plan pago y las funciones, los límites y esta documentación pueden cambiar. Vea qué incluye.

URLs de su tenant

Cada tenant tiene su propio host. Todas las URLs de esta documentación usan la variable $TENANT_HOST:

export TENANT_HOST="wispy-waterfall-3912.prod.vu-one.com"

Para	URL
API	`https://$TENANT_HOST/middleware/api/v1/...`
Token	`https://$TENANT_HOST/middleware/oauth2/token`
Discovery de OpenID Connect	`https://$TENANT_HOST/middleware/.well-known/openid-configuration`
Claves públicas (JWKS)	`https://$TENANT_HOST/middleware/oauth2/jwks`
SCIM 2.0	`https://$TENANT_HOST/middleware/scim/v2`
Consola	`https://$TENANT_HOST/vuone/es/signin/governance`

Lea los endpoints de OAuth desde el documento de discovery en lugar de escribirlos a mano.

Qué flujo usar

Su caso	Flujo	Guía
Sus usuarios ingresan a una aplicación web, móvil o de una sola página	Código de autorización con PKCE. Una aplicación de una sola página o móvil no puede guardar un secreto: registre un cliente con el método de autenticación Ninguno.	Autenticación
Un backend o un proceso programado llama a la API sin usuario	`client_credentials`	Autenticación
Mantener la sesión sin pedir el ingreso otra vez	`refresh_token`	Autenticación
Su sistema crea y administra usuarios	API de identidades y cuentas	Identidades y cuentas
Su aplicación envía un código por e-mail, un enlace mágico o pide TOTP	API de factores	Factores
Su directorio corporativo sincroniza usuarios y grupos	SCIM 2.0	SCIM

Los flujos de OAuth y las llamadas a /api/v1 necesitan un cliente OAuth registrado en la consola. Vea Clientes OAuth. SCIM usa un token propio que se crea en la consola. Vea SCIM en la consola.

Convenciones de la API

Autenticación de las llamadas

Todas las llamadas a /api/v1 llevan Authorization: Bearer $TOKEN. El token define el alcance: el tenant completo o un negocio. Los encabezados X-Business-Id, X-Channel-Id y X-Account-Scope fijan el contexto de la llamada dentro de ese alcance. Vea Autenticación.

Paginación

La mayoría de las listas usan el mismo sobre: currentPage, pageSize, totalElements, totalPages y content. La primera página es la 1. En la mayoría de los endpoints, si no envía pageSize, la API devuelve 10 elementos. Algunos endpoints usan otro valor predeterminado. Envíe pageSize en cada llamada para obtener un resultado previsible.

Errores

Un error llega en una de tres formas según la capa que responde: gateway, API de negocio u OAuth. En la API de negocio, decida con el campo codeKey, no con el texto de message. Vea Errores.

SDK

Durante la vista previa, los SDK no se distribuyen públicamente. Integre con HTTP y cualquier biblioteca estándar de OAuth 2.0 y OpenID Connect.

Prepare su código para el plan FREE

VU ONE FREE es una versión limitada. Cuando su código llama a una función del plan pago, la API responde 402 con el código 4020. Cuando la función está oculta en FREE, responde 404, en general sin cuerpo. Maneje los dos casos como estados esperados:

const res = await fetch(`https://${TENANT_HOST}/middleware/api/v1/...`, {
  headers: { Authorization: `Bearer ${token}` },
});

if (res.status === 402) {
  const body = await res.json();
  // body.code === 4020 y body.feature indica la función del plan pago.
  // No reintente: muestre un aviso o use una alternativa incluida en FREE.
}

Por ejemplo, si su flujo de ingreso usa un código por SMS, en FREE use el código por e-mail o TOTP. Vea qué incluye cada plan en FREE y plan pago.

Qué sigue

Inicio rápido

Su primer token y su primera llamada.

Autenticación

Código de autorización con PKCE, client_credentials y validación de tokens.

Errores

Formas de error, códigos y reintentos.

Conceptos

Tenant, negocio, canal, identidad y cuenta.

Empezar aquí

Administración

Desarrolladores

Guía para desarrolladores de VU ONE FREE

URLs de su tenant

Qué flujo usar

Convenciones de la API

Prepare su código para el plan FREE

Qué sigue

Inicio rápido

Autenticación

Errores

Conceptos