Cuentas, identidades y contraseñas

Esta página muestra cómo crear una identidad y una cuenta, cómo consultarlas y cómo verificar o cambiar contraseñas. Una identidad representa a una persona u organización. Una cuenta vincula esa identidad con un negocio o con el tenant, y le asigna un tipo de cuenta. Al terminar, usted tiene una persona con una cuenta y una contraseña que puede verificar desde su backend.

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.

Antes de empezar

Un token válido en $TOKEN. Obténgalo según Autenticación con OAuth 2.0 y OIDC.
El identificador del negocio y del canal donde va a crear la cuenta.
curl y jq instalados en su equipo.

Defina estas variables antes de seguir los ejemplos:

export TENANT_HOST="wispy-waterfall-3912.prod.vu-one.com"  # reemplace por el host de su tenant
export TOKEN="<access-token>"
export BUSINESS_ID="<business-id>"
export CHANNEL_ID="<channel-id>"

Flujo típico

Para dar de alta a una persona con contraseña, haga estas cuatro llamadas en orden. Los pasos 2, 3 y 4 usan los id que devuelven los pasos 1 y 2.

# 1. Cree la identidad y guarde su id
export IDENTITY_ID=$(curl -s -X POST "https://$TENANT_HOST/middleware/api/v1/identities" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"identityType": "PERSON", "name": "Juan Ejemplo", "metadata": {}}' | jq -r .id)

# 2. Cree la cuenta en un negocio y guarde su id
export ACCOUNT_ID=$(curl -s -X POST "https://$TENANT_HOST/middleware/api/v1/accounts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"accountScope": "BUSINESS", "businessId": "'"$BUSINESS_ID"'", "identityId": "'"$IDENTITY_ID"'", "accountType": "CUSTOMER", "metadata": {}, "claims": {}}' | jq -r .id)

# 3. Cree la contraseña de la cuenta
curl -s -X POST "https://$TENANT_HOST/middleware/api/v1/passwords" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"accountId": "'"$ACCOUNT_ID"'", "password": "<contraseña-inicial>", "businessId": "'"$BUSINESS_ID"'", "channelId": "'"$CHANNEL_ID"'"}' | jq .

# 4. Verifique la contraseña (200 sin cuerpo si es válida)
curl -i -X POST "https://$TENANT_HOST/middleware/api/v1/passwords/login" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"accountId": "'"$ACCOUNT_ID"'", "password": "<contraseña-inicial>"}'

Las secciones siguientes describen cada llamada, sus campos y sus respuestas.

Permisos

Cada endpoint pide un permiso con la forma sys_<área>:<acción>. Un token con role_admin cumple todos los permisos. Un usuario también puede hacer llamadas GET y POST sobre su propio accountId sin el permiso correspondiente.

Operación	Permiso
Crear identidad	`sys_identity:create`
Consultar identidad	`sys_identity:read`
Modificar identidad	`sys_identity:update`
Crear cuenta	`sys_account:create`
Consultar cuenta	`sys_account:read`
Modificar cuenta	`sys_account:update`
Crear contraseña	`sys_factor_password:create`
Verificar contraseña	`sys_factor_password:read`
Cambiar contraseña	`sys_factor_password:create`

Crear una identidad

Envíe un POST a /api/v1/identities.

string

requerido

Tipo de identidad. Valores: NONE, SERVICE, PERSON, DEVICE u ORGANIZATION.

string

requerido

Nombre de la identidad.

object

Datos adicionales en formato clave y valor.

string

Estado del ciclo de vida. Valores: NONE, REGISTERED, PENDING, ACTIVE, SUSPENDED, BLOCKED, DEACTIVATED, INACTIVE, DELETED o TERMINATED.

curl -s -X POST "https://$TENANT_HOST/middleware/api/v1/identities" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identityType": "PERSON",
    "name": "Juan Ejemplo",
    "metadata": {}
  }' | jq .

La API responde 201 con la identidad creada. La respuesta trae estos campos:

string

Identificador de la identidad (UUID).

string

Nombre de la identidad.

string

Tipo de identidad.

object

Datos adicionales.

string

Estado del ciclo de vida.

array

Cuentas vinculadas a la identidad.

array

Negocios en los que la identidad tiene cuenta.

boolean

Indica si la identidad es administradora del tenant.

Consultar identidades

Use GET /api/v1/identities para buscar identidades. Los filtros aceptados son name, identityType, lifecycleState, accountType, ids, businessId e include.

curl -s "https://$TENANT_HOST/middleware/api/v1/identities?name=Juan" \
  -H "Authorization: Bearer $TOKEN" | jq .

Para leer una identidad por su identificador, use GET /api/v1/identities/{id}.

curl -s "https://$TENANT_HOST/middleware/api/v1/identities/<identity-id>" \
  -H "Authorization: Bearer $TOKEN" | jq .

Modificar una identidad

Envíe un PATCH a /api/v1/identities/{id}. Los campos son name, metadata y lifecycleState. Envíe solo los campos que cambian. Si el cambio se completa, la API responde 204 sin cuerpo.

curl -i -X PATCH "https://$TENANT_HOST/middleware/api/v1/identities/<identity-id>" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Juan Ejemplo Actualizado"
  }'

Crear una cuenta

Una cuenta vincula una identidad con un negocio o con el tenant. Envíe un POST a /api/v1/accounts.

string

Alcance de la cuenta. Valores: BUSINESS o TENANT. Si lo omite, el valor es BUSINESS.

string

Identificador del negocio. Es obligatorio con accountScope BUSINESS. Con TENANT, no lo envíe. Una cuenta TENANT debe tener accountType WORKFORCE y usar el proveedor de identidad local.

string

requerido

Identificador de la identidad a la que pertenece la cuenta.

string

requerido

Tipo de cuenta. Valores: NONE, CUSTOMER, WORKFORCE o SERVICE.

string

Identificador del proveedor de identidad, si aplica.

object

Datos adicionales en formato clave y valor.

string

Estado del ciclo de vida de la cuenta. Valores: NONE, PROVISIONED, PENDING, ACTIVE, SUSPENDED, DEACTIVATED o DELETED.

object

Valores de claims por clave. Cada clave lleva un objeto con value (obligatorio, texto o lista de textos), isIdentifier y primaryIndex. Las claves dependen del esquema de su tenant. Consúltelas con GET /api/v1/tenant/identifier-claim-schema.

curl -s -X POST "https://$TENANT_HOST/middleware/api/v1/accounts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accountScope": "BUSINESS",
    "businessId": "<business-id>",
    "identityId": "<identity-id>",
    "accountType": "CUSTOMER",
    "metadata": {},
    "claims": {}
  }' | jq .

La API responde 201. La respuesta incluye estos campos principales:

string

Identificador de la cuenta (UUID).

string

Alcance de la cuenta: BUSINESS o TENANT.

string

Identificador del negocio de la cuenta.

string

Identificador de la identidad vinculada.

string

Tipo de cuenta.

string

Estado del ciclo de vida de la cuenta.

array

Identificadores de la cuenta, como el correo o el teléfono. Es una lista de textos.

string

Identificador principal de la cuenta.

array

Permisos que tiene la cuenta.

La respuesta también incluye businessName, identityProviderId, identityProviderType, identityName, metadata, scimLifecycleState, origin, externalId, suspendedAt y deprovisionedAt.

Consultar cuentas

Use GET /api/v1/accounts con filtros opcionales:

curl -s "https://$TENANT_HOST/middleware/api/v1/accounts?businessId=<business-id>" \
  -H "Authorization: Bearer $TOKEN" | jq .

Para leer una cuenta por su identificador, use GET /api/v1/accounts/{accountId}.

curl -s "https://$TENANT_HOST/middleware/api/v1/accounts/<account-id>" \
  -H "Authorization: Bearer $TOKEN" | jq .

Para buscar una cuenta por correo o teléfono, use GET /api/v1/accounts/identifier. El parámetro identifierType acepta ALL, EMAIL o PHONE.

curl -s "https://$TENANT_HOST/middleware/api/v1/accounts/identifier?filter=<texto>&identifierType=EMAIL" \
  -H "Authorization: Bearer $TOKEN" | jq .

Para listar las cuentas de una identidad, use GET /api/v1/accounts/identity/{identityId}.

Modificar una cuenta

Envíe un PATCH a /api/v1/accounts/{accountId} con metadata o lifecycleState. Si el cambio se completa, la API responde 204 sin cuerpo.

curl -i -X PATCH "https://$TENANT_HOST/middleware/api/v1/accounts/<account-id>" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "lifecycleState": "SUSPENDED"
  }'

Para cambiar los roles de una cuenta, envíe un PATCH a /api/v1/accounts/{accountId}/roles con las listas addedRoles y removedRoles (identificadores UUID de roles). Si el cambio se completa, la API responde 204 sin cuerpo.

curl -i -X PATCH "https://$TENANT_HOST/middleware/api/v1/accounts/<account-id>/roles" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "addedRoles": ["<role-id>"],
    "removedRoles": []
  }'

Contraseñas

La contraseña es un factor de la cuenta. Está incluida en VU ONE FREE, sin un flag adicional.

Crear una contraseña

Envíe un POST a /api/v1/passwords.

string

requerido

Identificador de la cuenta (UUID).

string

Contraseña inicial. Si la omite, VU ONE genera una contraseña temporal y la envía al destino de sendTo.

string

Identificador del negocio.

string

Identificador del canal.

boolean

Indica si la contraseña es temporal. Predeterminado: false.

string

Correo o teléfono al que se envía la contraseña temporal.

integer

Días de vigencia de la contraseña. Si no lo envía, se usa el valor de la política.

string

Nombre de la plantilla del mensaje, definida en la política de contraseña.

string

Nombre de usuario, usado en las validaciones de la política.

string

Fecha de nacimiento con el formato yyyyMMdd.

array

Lista de teléfonos de la cuenta.

curl -s -X POST "https://$TENANT_HOST/middleware/api/v1/passwords" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "<account-id>",
    "password": "<contraseña-inicial>",
    "businessId": "<business-id>",
    "channelId": "<channel-id>"
  }' | jq .

Si la política de contraseña tiene desactivadas las contraseñas temporales, la API rechaza una solicitud sin password. La respuesta con código 201 incluye estos campos:

string

Identificador del factor de contraseña.

string

Identificador de la cuenta.

string

Identificador del canal.

boolean

Indica si el factor está habilitado.

boolean

Indica si el factor está bloqueado.

boolean

Indica si el bloqueo fue automático, por intentos fallidos.

boolean

Indica si la contraseña es temporal.

string

Fecha de inicio de la vigencia (ISO 8601).

integer

Días de vigencia de la contraseña.

string

Fecha en que se desbloquea el factor (ISO 8601).

Fecha del último inicio de sesión correcto (ISO 8601).

En la respuesta de creación, los campos id, channelId y lastSuccessfulLogin no se completan. Si los necesita, consulte el factor con GET /api/v1/passwords/account/{accountId}.

Verificar una contraseña

Envíe un POST a /api/v1/passwords/login para comprobar que una contraseña es correcta.

curl -i -X POST "https://$TENANT_HOST/middleware/api/v1/passwords/login" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "<account-id>",
    "password": "<contraseña>"
  }'

Si la contraseña es válida, la API responde 200 sin cuerpo. Este endpoint no devuelve un token. Para obtener un token, use el flujo de Autenticación.

Cambiar una contraseña

Envíe un POST a /api/v1/passwords/change. Los campos accountId y password son obligatorios.

curl -i -X POST "https://$TENANT_HOST/middleware/api/v1/passwords/change" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "<account-id>",
    "password": "<nueva-contraseña>"
  }'

Si el cambio se completa, la API responde 204 sin cuerpo.

La longitud, el historial, los intentos fallidos y el bloqueo de la contraseña los define la política de contraseña. Consúltela con GET /api/v1/policies/password?businessId=<business-id>&channelId=<channel-id>. Vea la sección de políticas en Factores de autenticación en la API.

Para los códigos de error de estas operaciones, consulte Errores de la API de VU ONE FREE.

Qué sigue

Factores de autenticación en la API

Enrole y verifique factores para cada cuenta.

Autenticación con OAuth 2.0 y OIDC

Obtenga los tokens que usan estas llamadas.

Errores de la API de VU ONE FREE

Consulte los códigos de error de cada operación.

Identidades en la consola

Revise en la consola las identidades y cuentas que creó.

Empezar aquí

Administración

Desarrolladores

Cuentas, identidades y contraseñas

Antes de empezar

Flujo típico

Permisos

Crear una identidad

Consultar identidades

Modificar una identidad

Crear una cuenta

Consultar cuentas

Modificar una cuenta

Contraseñas

Crear una contraseña

Verificar una contraseña

Cambiar una contraseña

Qué sigue

Factores de autenticación en la API

Autenticación con OAuth 2.0 y OIDC

Errores de la API de VU ONE FREE

Identidades en la consola