Control API - tenant administración

FoxIDs tiene superficies Control API separadas para los operadores de implementación que administran tenants y para un tenant que administra su propia cuenta. Utilice las operaciones del operador para tenant aprovisionamiento y administración cruzada tenant. Utilice las operaciones de autoservicio cuando una integración deba limitarse a su propio tenant.

Antes de llamar a estas operaciones, configure Control API autenticación y derechos de acceso. Swagger sigue siendo la referencia exacta para tenant propiedades, opciones de plan y pago, reglas de validación y esquemas de respuesta:

API superficies

Operador de implementación

Las operaciones del operador se llaman en master tenant:

https://control.foxids.com/api/master/master

Operación	Punto final	Objetivo
Lista	`GET /!tenants`	Lista que no sea master tenants con filtros y paginación opcionales.
Conseguir	`GET /!tenant?name={name}`	Leer el recurso de administración de uno de tenant.
Crear	`POST /!tenant`	Proporcione un tenant, un administrador inicial y recursos predeterminados.
Actualizar	`PUT /!tenant`	Reemplace las propiedades editables tenant administradas por el operador.
Borrar	`DELETE /!tenant?name={name}`	Eliminar permanentemente un tenant y todos los datos de tenant.

Estas operaciones requieren derechos de acceso master-tenant. Están destinados a la administración de implementación confiable y a los servicios de aprovisionamiento SaaS.

Tenant autoservicio

Un tenant llama a sus propias operaciones a través de su entorno master:

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

Operación	Punto final	Objetivo
Conseguir	`GET /!mytenant`	Lea la cuenta tenant de la persona que llama y la configuración disponible.
Actualizar	`PUT /!mytenant`	Actualizar las propiedades de autoservicio permitidas.
Borrar	`DELETE /!mytenant`	Elimine permanentemente los datos de tenant y todos los de tenant de la persona que llama.

El autoservicio utiliza tenant derechos de acceso y no puede administrar otro tenant. Los cambios de plan, la configuración de pagos y los dominios personalizados también están sujetos a las políticas configuradas de la implementación.

Cambie el host en estos ejemplos para una implementación autohospedada y envíe el token de acceso en el encabezado Authorization: Bearer {access_token}.

Enumerar e identificar tenants

GET /!tenants acepta filterName, filterCustomDomain y paginationToken. Cuando se proporcionan ambos filtros, se devuelve un tenant cuando su nombre o dominio personalizado coincide. Los registros master tenant y de uso interno tenant no están incluidos.

Repita una solicitud paginada con los mismos filtros y el token opaco devuelto hasta que no se devuelva ningún token. No interprete ni modifique el token.

La tenant name minúscula es el identificador estable utilizado en las URL FoxIDs y Control API. Trátelo como una clave de automatización inmutable. Un dominio personalizado es una propiedad de marca y enrutamiento independiente y no debe usarse como el nombre de la ruta Control API tenant.

Aprovisionar un tenant

La creación de Tenant es una operación de aprovisionamiento compuesta. Una solicitud exitosa crea:

el registro tenant;
el entorno master de tenant y su método de autenticación de inicio de sesión predeterminado;
el usuario administrador inicial;
el recurso Control API y la aplicación Cliente de control;
los entornos predeterminados configurados de la implementación.

El administrador inicial puede recibir una contraseña proporcionada o establecer una contraseña a través del flujo de correo electrónico configurado. Proteja cualquier contraseña proporcionada y no registre el cuerpo de la solicitud.

La solicitud también puede seleccionar un plan e inicializar la configuración del cliente, las reclamaciones y el dominio personalizado cuando la implementación lo permita. Tenant la unicidad del nombre, las reglas del plan, la compatibilidad con dominios personalizados y los datos de administrador requeridos se validan antes de que se complete el aprovisionamiento. Si un error de cuenta o de datos interrumpe el aprovisionamiento, FoxIDs intenta limpiar los recursos creados por esa solicitud; sin embargo, los clientes deben tratar cualquier error como fallido y verificar el estado antes de volver a intentarlo con el mismo nombre tenant.

Actualizar la configuración de tenant

Las operaciones Tenant PUT son actualizaciones completas, no parches. Obtenga el recurso actual, conserve todas las propiedades editables que deben permanecer sin cambios, aplique el cambio previsto y envíe el modelo de solicitud completo para el operador o punto final de autoservicio seleccionado.

El recurso del operador incluye propiedades administradas por la implementación, como asignación de planes, verificación de dominio personalizado, configuración de uso y pago, moneda, IVA, precio por hora y datos del cliente. El recurso de autoservicio expone solo configuraciones que tenant puede administrar.

Cambiar un dominio personalizado mediante el autoservicio marca el dominio como no verificado hasta que se completa la verificación requerida. El plan seleccionado debe admitir un dominio personalizado. Utilice el operador API para gestionar el estado de verificación; no permita que un cliente tenant que no sea de confianza afirme que su propio dominio está verificado.

Eliminar un tenant

La eliminación Tenant es irreversible y en cascada. Elimina todos los entornos de tenant y todas las aplicaciones de ámbito, métodos de autenticación, usuarios, sesiones, concesiones, claves y otros datos de FoxIDs. También elimina la configuración de nivel tenant y el enrutamiento de dominio personalizado. El master tenant no se puede eliminar. Los registros ya enviados a un repositorio externo permanecen sujetos a la política de retención y eliminación de ese repositorio.

Antes de la eliminación, detenga el tráfico, exporte la configuración o los datos que deben conservarse, cancele o concilie la facturación externa cuando corresponda y verifique el nombre técnico de tenant. Requerir confirmación explícita en las herramientas del operador. No utilice la eliminación de tenant para deshabilitar el acceso temporalmente; en su lugar, deshabilite o actualice los usuarios, aplicaciones o métodos de autenticación relevantes.

Guía de automatización y seguridad

Prefiere puntos finales de autoservicio cuando un cliente solo necesita administrar su propio tenant.
Restrinja las credenciales del operador a un servicio de aprovisionamiento pequeño y confiable.
Mantenga estable el nombre técnico tenant y guárdelo independientemente de los datos de visualización, de cliente y de dominio personalizado.
Utilice get-modify-put para que una integración anterior no restablezca las nuevas propiedades.
Utilice la paginación para tenant inventarios y concilie por nombre técnico.
Trate la creación y eliminación de tenant como acciones de administración compuestas de larga duración; utilice tiempos de espera de cliente apropiados y verifique el estado final después de una respuesta interrumpida.
Espere que las solicitudes de creación, actualización y eliminación aparezcan en el registro de auditoría de Control. Las operaciones de lectura no se escriben como eventos de auditoría.

Respuestas de error comunes

400 Bad Request cuando los datos de tenant administrador, plan, pago, cliente o dominio personalizado no son válidos.
401 Unauthorized cuando falta el token de acceso o no es válido.
403 Forbidden cuando la persona que llama carece del derecho de acceso master o tenant requerido.
404 Not Found cuando el tenant seleccionado no existe.
409 Conflict cuando ya existe un nombre tenant u otro valor único.

Utilice el cuerpo de la respuesta para los detalles de validación y Swagger UI para las respuestas declaradas por cada operación.