Control API - entornos
Utilice FoxIDs Control API para enumerar, crear, configurar y eliminar entornos en un tenant. Un entorno se denomina track en Control API rutas y esquemas.
Antes de llamar a estas operaciones, configure Control API autenticación y derechos de acceso. Swagger sigue siendo la referencia exacta para todas las propiedades del entorno, reglas de validación y esquemas de respuesta:
Base de punto final
La administración del entorno se realiza a través del entorno master de tenant. Los ejemplos utilizan FoxIDs Cloud:
https://control.foxids.com/api/{tenant_name}/master
Reemplace {tenant_name} con el nombre técnico de tenant. Cambie el host para una implementación autohospedada. Envíe el token de acceso Control API en el encabezado Authorization: Bearer {access_token}.
Las operaciones del entorno requieren el correspondiente tenant o derecho de acceso al entorno. Los entornos devueltos por las operaciones de lista se limitan a aquellos a los que puede acceder la persona que llama. Utilice la Control API jerarquía de derechos de acceso para otorgar solo la operación read, create, update o delete requerida.
Operaciones ambientales
Las operaciones del entorno se agrupan en tenant tracks en Swagger.
| Operación | Punto final | Objetivo |
|---|---|---|
| Lista | GET /!tracks |
Enumere entornos accesibles con filtrado y paginación opcionales. |
| Conseguir | GET /!track?name={name} |
Obtenga la configuración completa para un entorno. |
| Crear | POST /!track |
Cree un entorno y su método de autenticación de inicio de sesión predeterminado. |
| Actualizar | PUT /!track |
Reemplace la configuración del entorno editable. |
| Borrar | DELETE /!track?name={name} |
Eliminar permanentemente un entorno y sus datos. |
Agregue cada punto final a la base de puntos finales.
Enumerar e identificar entornos
GET /!tracks acepta filterName y paginationToken. El filtro coincide con el name técnico o el displayName, independientemente del caso.
La respuesta contiene una colección data y un paginationToken opaco. Para leer la página siguiente, repita la misma solicitud con el token devuelto y el mismo filtro. Continúe hasta que la respuesta ya no contenga un token. No interprete ni modifique el token.
El name técnico identifica el entorno en Control API URL y en operaciones posteriores de obtención, actualización y eliminación. Trátelo como una clave de automatización estable. Utilice displayName para el texto presentado a los administradores.
Crear un ambiente
Los nombres de los entornos están en minúsculas. Proporcione un name cuando una integración requiera una URL predecible u omítalo y deje que FoxIDs genere un nombre único. Una solicitud debe contener un nombre o un nombre para mostrar.
La creación de un entorno también crea el método de autenticación de inicio de sesión predeterminado. Otras aplicaciones, métodos de autenticación, usuarios, claves y recursos del entorno se configuran por separado después de la creación.
El plan tenant puede limitar la cantidad de entornos. Por lo tanto, una solicitud de creación puede fallar cuando se alcanza el límite. Las operaciones de creación simultáneas limitadas por el plan pueden devolver 423 Locked; Vuelva a intentarlo después de un breve retraso.
Actualizar la configuración del entorno
PUT /!track es una actualización completa, no un parche. Primero obtenga el entorno actual, conserve todas las propiedades que deben permanecer sin cambios, aplique los cambios previstos y envíe la representación editable completa.
El técnico name selecciona el entorno y no se le cambia el nombre mediante una actualización. Las configuraciones editables incluyen la visualización y los detalles de la empresa, la duración de la secuencia, el comportamiento de mapeo de reclamos, la protección contra fallas de inicio de sesión, las políticas de contraseñas, la integración de directorios y contraseñas externas y los dominios iframe permitidos. Algunos recursos relacionados, incluidos SMS, correo electrónico, asignaciones de reclamos, textos, claves y certificados, tienen puntos finales dedicados y no se reemplazan mediante la operación del entorno.
Las solicitudes posteriores utilizan la configuración actualizada después de que FoxIDs invalide la caché de configuración del entorno.
Eliminar un entorno
Eliminar un entorno es una operación en cascada irreversible. Elimina la configuración del entorno y todos los datos relacionados con ese entorno, incluidas sus aplicaciones, métodos de autenticación, usuarios, sesiones, concesiones, claves y otros recursos. También se eliminan los enlaces de otros entornos al entorno eliminado.
No utilice la eliminación del entorno como una forma de borrar los recursos seleccionados. Elimine o actualice esos recursos individualmente cuando el entorno deba permanecer disponible. Antes de eliminar un entorno, detenga el tráfico hacia él, exporte cualquier configuración o datos que deban conservarse y verifique el nombre técnico en la solicitud.
Guía de automatización
- Mantenga estables los nombres técnicos y guárdelos por separado de los nombres para mostrar.
- Utilice la paginación de lista incluso cuando un tenant tenga actualmente solo unos pocos entornos.
- Utilice un flujo de trabajo get-modify-put para evitar restablecer involuntariamente la configuración agregada en una versión más reciente de FoxIDs.
- Cree recursos dependientes solo después de que la solicitud de creación del entorno se realice correctamente.
- Trate la eliminación como una operación de desmontaje permanente y requiera una confirmación explícita en las herramientas administrativas.
- 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 Requestcuando los datos o el nombre del entorno no son válidos, se utiliza un nombre reservado o se alcanza un límite del plan.401 Unauthorizedcuando falta el token de acceso o no es válido.403 Forbiddencuando la persona que llama carece del derecho de acceso requerido.404 Not Foundcuando el entorno seleccionado no existe.409 Conflictcuando ya existe un entorno con el mismo nombre técnico.423 Lockedcuando una operación de creación limitada al plan está bloqueada temporalmente.
Utilice el cuerpo de la respuesta para los detalles de validación y Swagger UI para las respuestas declaradas por cada operación.