Control API - usuarios y aplicaciones de autenticación

Utilice FoxIDs Control API para aprovisionar usuarios internos y administrar las aplicaciones de autenticación registradas por cada usuario. Esta guía se centra en las operaciones que permiten sincronizar registros entre deployments de FoxIDs.

Antes de llamar a estas operaciones, configure la autenticación y los derechos de acceso de Control API. Swagger sigue siendo la referencia exacta para todas las propiedades de usuario, filtros, reglas de validación y esquemas de response:

• Swagger (OpenAPI) JSON
• Swagger UI

Base de endpoints

Los ejemplos utilizan FoxIDs Cloud:

https://control.foxids.com/api/{tenant_name}/{track_name}

Sustituya {tenant_name} por el nombre del tenant y {track_name} por el nombre técnico del entorno. Cambie el host para un deployment self-hosted. Envíe el access token de Control API en el header Authorization: Bearer {access_token}.

Las operaciones de usuarios y aplicaciones de autenticación requieren un derecho de usuario para el entorno de destino. Conceda solo la operación read, create, update o delete necesaria mediante la jerarquía de derechos de Control API.

Identificadores de usuario

Cada usuario interno debe tener al menos un identificador de inicio de sesión: correo electrónico, teléfono o nombre de usuario. Los correos y nombres de usuario se normalizan a minúsculas y se eliminan los espacios iniciales y finales.

Las operaciones individuales identifican al usuario con el query parameter email, phone o username. La response también contiene un userId generado por el servidor. Es único y persistente, incluso si cambia un identificador, y debe usarse para asociar aplicaciones de autenticación u otros recursos.

Operaciones de usuario

Las operaciones individuales se agrupan bajo tenant users en Swagger.

Use phone={phone} o username={username} en lugar de email={email} cuando corresponda. Añada cada endpoint a la base de endpoints.

Listar y filtrar usuarios

GET /!users admite filterEmail, filterPhone, filterUsername, filterUserId y filterClaimValue. Cada filtro busca coincidencias parciales sin distinguir mayúsculas. Con varios filtros, se devuelve el usuario si cualquiera coincide.

La response contiene una collection data y un paginationToken opaco. Repita el mismo request con el valor devuelto como paginationToken para obtener la página siguiente. Continúe hasta que no haya token. No lo interprete ni modifique.

La response indica si hay contraseña y cuándo cambió por última vez, pero nunca devuelve la contraseña ni su hash actual.

Crear un usuario

El create-request admite estado de cuenta, identificadores verificados, claims personalizados, política de contraseña, configuración por correo o SMS y ajustes MFA por usuario. Este ejemplo crea un usuario sin contraseña y exige configurarla por correo:

POST https://control.foxids.com/api/{tenant_name}/{track_name}/!user
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "email": "alice@example.com",
  "emailVerified": true,
  "setPasswordEmail": true,
  "claims": [{ "claim": "role", "values": ["employee"] }]
}

Un create-request puede incluir contraseña en texto claro, campos de hash admitidos o ninguna credencial. Nunca envíe ambos formatos. Las contraseñas en claro se validan con la política elegida; los hashes importados no. Sin credenciales, use setPasswordEmail o setPasswordSms si el usuario debe crear una contraseña al iniciar sesión.

Crear un usuario existente devuelve 409 Conflict y se aplica el límite de usuarios del plan del tenant. Una operación de usuario simultánea puede bloquear temporalmente la creación; reintente 423 Locked tras una breve espera.

Actualizar un usuario

PUT /!user es una actualización completa, no un patch. Lea el usuario actual, conserve las propiedades sin cambios, aplique los cambios y envíe toda la representación editable. La collection de claims y los flags de cuenta/MFA se sustituyen. Las contraseñas y registros de aplicaciones tienen operaciones propias.

Identifique al usuario con email, phone o username. Para cambiar un identificador, mantenga su valor actual y establezca updateEmail, updatePhone o updateUsername. Una cadena vacía lo elimina; omitir la propiedad lo conserva. Mantenga al menos un identificador de inicio de sesión.

Cambiar disableAccount de false a true revoca los refresh token grants y sesiones activas. Reactivar permite nuevos inicios de sesión, pero no restaura las sesiones revocadas.

Administrar contraseñas

Use PUT /!usersetpassword para administración o migración:

• Proporcione password para aplicar la política y actualizar el historial.
• Proporcione passwordHashAlgorithm, passwordHash y passwordHashSalt para importar un hash admitido sin validar la política.
• Omita ambos formatos para quitar la contraseña actual.

passwordLastChanged es tiempo Unix opcional en segundos. changePassword obliga a elegir una nueva contraseña en el siguiente inicio de sesión aplicable. Use PUT /!userchangepassword cuando conozca la actual; se verifica y la nueva se valida contra la política y el historial.

El endpoint de historial está destinado a migración y recuperación controladas. Su detalle contiene material de hash y PUT sustituye todo el historial. Protéjalo como los hashes importados y no registre request/response bodies.

Aprovisionamiento masivo

PUT /!users admite entre 1 y 1.000 usuarios por request. Como máximo 100 entries pueden incluir contraseñas en claro. Los requests sin ellas, incluidos hashes precalculados admitidos, pueden incluir 1.000 usuarios.

La carga masiva crea o sustituye usuarios; no combina propiedades ni puede renombrar identificadores. Trátela como una importación de sustitución. Use la actualización individual para conservar el estado y el userId persistente.

DELETE /!users admite entre 1 y 1.000 correos, teléfonos o nombres de usuario en userIdentifiers. Consulte Cargar muchos usuarios para formatos, rendimiento y seed tool.

Eliminar usuarios y revocar acceso

La eliminación individual o masiva revoca refresh token grants y sesiones activas antes de borrar la cuenta. Es permanente. Use las operaciones delete de aplicaciones de autenticación para quitar solo sus registros.

Los requests de creación, actualización, contraseña y eliminación se incluyen en el audit log de Control. Las lecturas no se escriben como audit-events.

Registros de aplicaciones de autenticación

Las operaciones de aplicaciones de autenticación se agrupan bajo tenant user authenticator apps en Swagger. Una operación de lista devuelve resúmenes seguros, mientras que la operación de detalle devuelve los datos confidenciales necesarios para una sincronización controlada.

Añada cada endpoint a la base de endpoints. Por ejemplo:

GET https://control.foxids.com/api/{tenant_name}/{track_name}/!userauthenticatorapps?userId=e061ed17-7b44-48a8-b224-ecdb800ed5cc
Authorization: Bearer {access_token}

Recurso de registro

La creación y la actualización utilizan el recurso de registro completo:

{
  "userId": "e061ed17-7b44-48a8-b224-ecdb800ed5cc",
  "id": "7a772286-76a2-4f17-a0f8-4e927bb1772d",
  "createTime": 1785769200,
  "secret": "TOTP-SHARED-SECRET",
  "recoveryCode": {
    "hashAlgorithm": "P2HS512:10",
    "hash": "RECOVERY-CODE-HASH",
    "hashSalt": "RECOVERY-CODE-SALT"
  }
}

Las propiedades se comportan del siguiente modo:

• userId es el ID estable del usuario de FoxIDs.
• id es un ID de registro persistente proporcionado por el cliente al crear. Selecciona el registro al actualizar y no puede cambiarse.
• createTime se expresa en segundos Unix. Es opcional al crear y de forma predeterminada usa la hora actual. Si se omite al actualizar, se conserva el valor existente.
• secret es el TOTP secret compartido y es obligatorio al crear y actualizar.
• recoveryCode contiene los datos de hash del recovery code y se omite cuando no hay un recovery code configurado.

Un usuario puede tener como máximo cinco registros de aplicaciones de autenticación. Crear con un ID existente devuelve 409 Conflict; crear después de alcanzar el límite devuelve 400 Bad Request.

Sincronizar registros

Un servicio de sincronización puede combinar la Authenticator App notification API interactiva con estas operaciones de Control API:

1. Reciba la notification registered que contiene user_id y registration_id.
2. Obtenga el registro del source deployment mediante la operación de detalle.
3. Cree el registro en el target deployment o actualícelo si ya existe el mismo ID.

Las operaciones de Control API para crear, actualizar y eliminar no llaman a la Authenticator App notification API. Por tanto, la sincronización no genera un bucle de notification.

Seguridad

Las operaciones de detalle, creación y actualización exponen o aceptan un secret de aplicación de autenticación y datos de hash del recovery code. Conceda el derecho de usuario necesario solo a clientes de confianza, utilice TLS, proteja los payloads almacenados y no registre los request o response bodies.

Utilice la operación de lista cuando solo necesite los ID de registro y las horas de creación. No devuelve el secret ni los datos de hash del recovery code.

Propiedad de compatibilidad

La propiedad activeTwoFactorApp de la API general de usuario está deprecated y se prevé eliminarla después del 1 de agosto de 2027. En una update-request, false sigue eliminando todos los registros por compatibilidad; true o un valor omitido los deja sin cambios. Las integraciones nuevas deben usar los endpoints de aplicaciones de autenticación.

Responses de error

Los responses de error habituales de usuarios y aplicaciones de autenticación son:

• 400 Bad Request si los identificadores, credenciales, filtros o datos son inválidos, o se alcanzó el límite de registros.
• 401 Unauthorized si falta el access token o no es válido.
• 403 Forbidden si el cliente no tiene el derecho de usuario necesario para el entorno.
• 404 Not Found si el usuario o registro de aplicación no existe.
• 409 Conflict si el usuario ya existe o se reutiliza un ID de registro.
• 423 Locked si la creación o importación masiva está bloqueada temporalmente. Reintente tras una breve espera.

Utilice el response body para ver los detalles de validación. Consulte Swagger UI para los responses declarados por cada operación.

Documentación relacionada

• Autenticación y derechos de acceso de Control API
• Descripción general de FoxIDs Control
• Usuarios internos
• Autenticación de dos factores y multi-factor
• Cargar muchos usuarios