Plataforma: Claves de API

Resumen

Las claves de API de la plataforma son credenciales que se utilizan para solicitar tokens portadores para las API de administración de la plataforma de GW Apps. La referencia de API actual cubre a los Usuarios, los Roles de aplicación y los Roles compartidos. Las claves de API de la plataforma son configuradas por un Superadministrador en la Configuración de la plataforma.

Una clave de API de la plataforma no otorga automáticamente acceso a todas las operaciones o recursos. Cada solicitud está limitada por los ámbitos seleccionados en la clave y los permisos de la identidad de usuario de GW Apps proporcionada cuando se solicita el token portador.

Las claves de API de la plataforma son diferentes de las claves de API de las aplicaciones. Usa una clave de API de aplicación para los puntos finales de aplicaciones, formularios y registros. Usa una clave de API de la plataforma para los puntos finales a nivel de plataforma que se describen en su Referencia de API.

Acceda al panel de claves de API

1. Iniciar sesión como Superadministrador.
2. Abre el menú de tu cuenta o el ícono de configuración y selecciona Configuración de la plataforma.
3. Seleccionar claves de API.

Campo	Descripción
Crear clave de API	Crea una configuración de clave de API para la plataforma. El diálogo inicial solicita un nombre y una descripción opcional.
Habilitado	Habilita o deshabilita la clave. Deshabilite una clave cuando se deba detener una integración sin eliminar su configuración.
Generar Nueva Clave	Crea una clave de reemplazo e invalida el valor anterior. Coordine el cambio antes de usar este comando.
Referencia de la API	Abre la referencia de administración de plataforma para autenticación, filtros, Usuarios, Roles de aplicación y Roles compartidos.
Editar	Cambia el nombre, la descripción, las identidades permitidas, las entidades o los ámbitos.
Quitar	Elimina la configuración. Elimínala únicamente después de confirmar que ninguna integración activa la utiliza.

Crear y configurar una clave de API de plataforma

1. Seleccione Crear clave de API.
2. Ingrese un nombre que identifique la integración y el entorno, como Directory Sync — Production.
3. Agregue una descripción opcional que registre el propietario, el propósito, el sistema externo y las operaciones esperadas.
4. Seleccione Crear. La configuración se añade al panel de claves de API.
5. Abra el menú de fila para la nueva clave y seleccione Editar.
6. En Detalles de seguridad, elija el tipo de seguridad adecuado. Cuando se seleccione Usuarios específicos, busque y agregue únicamente los administradores o las identidades de servicio que la integración pueda usar.

7. En Detalles de acceso, seleccione una entidad y sus alcances permitidos. Las entidades disponibles son Usuarios, Roles de aplicación y Roles compartidos.
8. Seleccione + Agregar acceso para añadir otra fila de entidad y alcance. Use la X a la derecha de una fila para eliminar el acceso que no sea necesario.

9. Revisa todos los alcances seleccionados y aplica el principio de mínimo privilegio.

10. Seleccione Guardar.
11. Desde el menú de la fila, seleccione Generar nueva clave cuando esté listo para obtener o rotar la credencial. Almacénela en un sistema de gestión de secretos aprobado; no la coloque en el código fuente, la documentación, las capturas de pantalla ni en mensajes compartidos.

12. Desde el menú de filas, seleccione Referencia de API y use la referencia actual al implementar y probar la integración.

Tipo de seguridad y usuario efectivo

Campo	Descripción
Usuarios específicos	Solo las identidades de aplicaciones de GW enumeradas se pueden proporcionar cuando un cliente solicita un token de portador con esta clave. Esto se recomienda para la mayoría de las integraciones.
Todos los usuarios del dominio	Un cliente que posee la clave puede solicitar un token para cualquier usuario de dominio elegible. Se siguen aplicando los permisos de usuario normales, pero la exposición tiene un impacto mayor.
Correo electrónico del usuario	Identifica al usuario de GW Apps efectivo para el token y las llamadas posteriores a la API. El usuario debe ser elegible según los Detalles de seguridad.

El acceso efectivo es la intersección entre la entidad y el ámbito seleccionados para la clave, los permisos del usuario efectivo y la seguridad aplicable de la plataforma. La selección de un ámbito no otorga al usuario un acceso que de otra manera no tendría.

Entidades y alcances de acceso actuales

Usuarios

• Crear usuario
• Suspender usuario
• Activar usuario
• Ver y buscar usuarios
• Obtener acceso de usuario

Roles de aplicación

• Crear rol de aplicación
• Actualizar rol de aplicación
• Ver y buscar roles de la aplicación
• Obtener rol de aplicación
• Agregar miembros a un rol de la aplicación
• Eliminar miembros del rol de aplicación

Roles Compartidos

• Crear rol compartido
• Actualizar rol compartido
• Eliminar rol compartido
• Ver y buscar roles compartidos
• Agregar usuario a rol compartido
• Eliminar usuario del rol compartido
• Listar miembros del rol compartido

Use la Referencia de la API abierta desde la clave seleccionada como fuente autorizada para los puntos de conexión, las propiedades de solicitud, las estructuras de respuesta y los ámbitos disponibles actualmente en su entorno.

Utilizar la referencia de la API de la plataforma

La Referencia de la API proporciona las estructuras de solicitud actuales, los parámetros, las solicitudes de ejemplo, las respuestas y las definiciones de recursos para los puntos de conexión de administración de la plataforma.

Autenticación

Siga la página de Autenticación para intercambiar la clave de API de la plataforma y una identidad de usuario elegible de GW Apps por un access_token. Envíe el token devuelto en el encabezado Authorization en solicitudes posteriores. Los ámbitos de las claves y los permisos efectivos del usuario continúan limitando cada solicitud.

Filtros

Los puntos de conexión de búsqueda utilizan las estructuras de filtro documentadas en la referencia. La página de Filtros enumera cada operador, los campos compatibles, el tipo de valor esperado y un ejemplo. También muestra cómo combinar condiciones con grupos OR y AND. Copie la estructura actual en lugar de adivinar los nombres de los operadores o el anidamiento de la carga útil.

Usuarios

La API de Gestión de Usuarios documenta el recurso de Usuario y los puntos de conexión para Crear Usuarios, Suspender Usuarios, Activar Usuarios, Buscar Usuarios, Obtener Usuario y Obtener Acceso de Usuario. Cada página de punto de conexión incluye su solicitud HTTP, parámetros o cuerpo de la solicitud, ejemplo de solicitud y respuesta.

Roles de aplicación

La API de Gestión de Roles de Aplicación documenta los puntos de conexión para Crear Rol de Aplicación, Actualizar Rol de Aplicación, Buscar Roles de Aplicación, Obtener Rol de Aplicación, Agregar Miembros y Eliminar Miembros.

El tipo de rol controla lo que se puede cambiar. Los roles de sistema o de plataforma son de solo lectura, incluida la membresía. Los roles de diseñador permiten agregar o eliminar miembros, pero su nombre y descripción no se pueden modificar. Los roles que no son específicos de una aplicación se administran como Roles compartidos y no se pueden modificar a través de los puntos de conexión de roles de aplicación. La modificación completa es compatible únicamente para los roles específicos de aplicación que no son roles de sistema, plataforma o diseñador. Las modificaciones no compatibles devuelven 403 Prohibido.

Roles Compartidos

La API de administración de roles compartidos documenta el recurso de roles compartidos y los puntos de conexión para crear, actualizar, eliminar, buscar, recuperar, agregar usuarios, eliminar usuarios y listar miembros. Revise el ámbito requerido y el ejemplo de solicitud del punto de conexión antes de implementarlo.

Ciclo de vida de tokens y credenciales

• Trate la clave de API como un secreto de larga duración que se utiliza únicamente para solicitar tokens de portador de corta duración.
• Solicite un nuevo token portador cuando el token actual expire. Siga la Referencia de API de la plataforma generada para conocer el comportamiento actual del token.
• Rota las claves periódicamente y de inmediato después de una sospecha de exposición. Generar nueva clave invalida el valor anterior, así que coordina la actualización del sistema consumidor.
• Desactivar una llave cuando las llamadas deban detenerse pero su configuración deba conservarse.
• Elimine las claves no utilizadas solo después de confirmar su propietario y sus dependencias.

Probando

1. Probar la operación de lectura o búsqueda menos permisiva requerida por la integración.
2. Prueba con la identidad de usuario efectiva exacta que usará producción.
3. Confirme que una identidad, entidad o ámbito no aprobados sean rechazados.
4. Para los roles de aplicación, confirme que las restricciones de los roles del sistema, de la plataforma, de diseñador y no específicos de la aplicación se comportan según lo documentado.
5. Confirma que la desactivación de la clave detiene las nuevas solicitudes.
6. Registre el nombre de la clave, el propietario, el entorno, los ámbitos aprobados y la fecha de rotación sin registrar el valor del secreto.

Solución de problemas

Campo	Descripción
400 Solicitud incorrecta	Verifique la solicitud de token, los parámetros, la estructura del filtro o la carga útil con la referencia de la API actual.
401 No autorizado	Verifique la clave, la expiración del token de portador, el usuario efectivo, el alcance seleccionado y los permisos del usuario.
403 Prohibido	Revisa el ámbito de la clave, la política de la plataforma, los permisos de usuario efectivo y las reglas de modificación de roles de aplicación.
404 No encontrado	Verifique el extremo y el identificador del recurso, y confirme que el usuario efectivo pueda acceder al recurso.
429 Demasiadas solicitudes	Reduce la frecuencia de las solicitudes y vuelve a intentar con un retraso creciente.
Las llamadas se interrumpen después de rotar	Actualice el servicio consumidor con la clave recién generada; el valor anterior ya no es válido.

Registro de eventos y respuesta a incidentes

• Registre el nombre de la configuración o identificador interno, el correo electrónico del usuario efectivo, el punto de extremo, la hora, el estado del resultado y un identificador de correlación cuando esté disponible.
• No registre la clave de API, el token de portador, el encabezado de autorización ni datos sensibles de solicitudes y respuestas.
• Si una clave puede haber quedado expuesta, desactívela, genere un reemplazo, actualice la integración autorizada, revise los registros pertinentes y elimine los ámbitos o usuarios innecesarios antes de restablecer el servicio.