> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vu-one.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cuentas, identidades y contraseñas

> Cree identidades y cuentas, consulte sus datos y administre contraseñas en VU ONE FREE, con ejemplos de curl, permisos y respuestas.

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.

> [!WARNING]
>
> **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](https://docs.vu-one.com/vu-one/plan-free.md).

## Antes de empezar

* Un token válido en `$TOKEN`. Obténgalo según [Autenticación con OAuth 2.0 y OIDC](https://docs.vu-one.com/vu-one/desarrolladores/autenticacion.md).
* 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:

```bash theme={null}
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.

```bash theme={null}
# 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`.

**identityType** `string` *required*

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

**name** `string` *required*

Nombre de la identidad.

**metadata** `object`

Datos adicionales en formato clave y valor.

**lifecycleState** `string`

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

```bash theme={null}
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:

**id** `string`

Identificador de la identidad (UUID).

**name** `string`

Nombre de la identidad.

**identityType** `string`

Tipo de identidad.

**metadata** `object`

Datos adicionales.

**lifecycleState** `string`

Estado del ciclo de vida.

**accounts** `array`

Cuentas vinculadas a la identidad.

**businesses** `array`

Negocios en los que la identidad tiene cuenta.

**tenantAdmin** `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`.

```bash theme={null}
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}`.

```bash theme={null}
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.

```bash theme={null}
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`.

**accountScope** `string`

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

**businessId** `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.

**identityId** `string` *required*

Identificador de la identidad a la que pertenece la cuenta.

**accountType** `string` *required*

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

**identityProviderId** `string`

Identificador del proveedor de identidad, si aplica.

**metadata** `object`

Datos adicionales en formato clave y valor.

**lifecycleState** `string`

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

**claims** `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`.

```bash theme={null}
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:

**id** `string`

Identificador de la cuenta (UUID).

**accountScope** `string`

Alcance de la cuenta: `BUSINESS` o `TENANT`.

**businessId** `string`

Identificador del negocio de la cuenta.

**identityId** `string`

Identificador de la identidad vinculada.

**accountType** `string`

Tipo de cuenta.

**lifecycleState** `string`

Estado del ciclo de vida de la cuenta.

**identifiers** `array`

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

**primaryIdentifier** `string`

Identificador principal de la cuenta.

**permissions** `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:

```bash theme={null}
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}`.

```bash theme={null}
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`.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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`.

**accountId** `string` *required*

Identificador de la cuenta (UUID).

**password** `string`

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

**businessId** `string`

Identificador del negocio.

**channelId** `string`

Identificador del canal.

**temporal** `boolean`

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

**sendTo** `string`

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

**expirationInDays** `integer`

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

**template** `string`

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

**userName** `string`

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

**birthDate** `string`

Fecha de nacimiento con el formato `yyyyMMdd`.

**phoneNumber** `array`

Lista de teléfonos de la cuenta.

```bash theme={null}
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:

**id** `string`

Identificador del factor de contraseña.

**accountId** `string`

Identificador de la cuenta.

**channelId** `string`

Identificador del canal.

**enabled** `boolean`

Indica si el factor está habilitado.

**locked** `boolean`

Indica si el factor está bloqueado.

**lockedAuto** `boolean`

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

**temporal** `boolean`

Indica si la contraseña es temporal.

**expirationStartTimeStamp** `string`

Fecha de inicio de la vigencia (ISO 8601).

**expirationDaysToLive** `integer`

Días de vigencia de la contraseña.

**unlockDate** `string`

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

**lastSuccessfulLogin** `string`

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

> [!NOTE]
>
> 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.

```bash theme={null}
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](https://docs.vu-one.com/vu-one/desarrolladores/autenticacion.md).

### Cambiar una contraseña

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

```bash theme={null}
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.

> [!TIP]
>
> 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](https://docs.vu-one.com/vu-one/desarrolladores/factores.md).

Para los códigos de error de estas operaciones, consulte [Errores de la API de VU ONE FREE](https://docs.vu-one.com/vu-one/desarrolladores/errores.md).

## Qué sigue

> [card] [Factores de autenticación en la API](https://docs.vu-one.com/vu-one/desarrolladores/factores.md)
>
> Enrole y verifique factores para cada cuenta.

> [card] [Autenticación con OAuth 2.0 y OIDC](https://docs.vu-one.com/vu-one/desarrolladores/autenticacion.md)
>
> Obtenga los tokens que usan estas llamadas.

> [card] [Errores de la API de VU ONE FREE](https://docs.vu-one.com/vu-one/desarrolladores/errores.md)
>
> Consulte los códigos de error de cada operación.

> [card] [Identidades en la consola](https://docs.vu-one.com/vu-one/admin/identidades.md)
>
> Revise en la consola las identidades y cuentas que creó.


## Related topics

- [Autenticación con OAuth 2.0 y OIDC](https://docs.vu-one.com/vu-one/desarrolladores/autenticacion.md)
- [Errores de la API de VU ONE FREE](https://docs.vu-one.com/vu-one/desarrolladores/errores.md)
- [Factores de autenticación en la API](https://docs.vu-one.com/vu-one/desarrolladores/factores.md)
- [Aprovisionamiento con SCIM 2.0](https://docs.vu-one.com/vu-one/desarrolladores/scim.md)
- [Administrar identidades y cuentas](https://docs.vu-one.com/vu-one/admin/identidades.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.