SoSafe API – Soporte de SoSafe

Introducción

¿Qué hace el SoSafe API?

El SoSafe API permite a clientes y partners como usted acceder directamente en su software a información importante sobre sus medidas de ciberseguridad de SoSafe, sin necesidad de iniciar sesión ni ver o descargar información manualmente en el manager. Con esta API, puede recuperar automáticamente información que incluye, entre otros:

Información de empleados: ¿Quiénes son los usuarios inscritos en las medidas de concienciación de SoSafe?
Progreso de formación de empleados: ¿Hasta qué punto han avanzado sus empleados en la formación en ciberseguridad?
Finalización de lecciones: ¿Quién ha completado sus lecciones y quién aún tiene algunas pendientes?
Participación del equipo: Obtenga información sobre el nivel de participación de los distintos grupos en la formación.
Niveles de riesgo y comportamiento seguro: ¿Qué capacidad tienen los empleados para identificar correos electrónicos de phishing simulados y con qué frecuencia los notifican?

Puede utilizar esta información para hacer un seguimiento del progreso de los usuarios, crear informes o asegurarse de que todos cumplen con la formación requerida. Esto facilitará la promoción de un comportamiento seguro.

¿Por qué es relevante para nuestros clientes y partners?

La API pública mejora la oferta actual de SoSafe al proporcionar acceso automatizado y sin interrupciones a los datos de formación en ciberseguridad para clientes y partners. Aunque el manager y la funcionalidad de exportación de datos de SoSafe han sido herramientas fiables, la API abre nuevas posibilidades para una gestión de datos más eficiente y flexible, al permitir la integración directa en sus flujos de trabajo.

Muchos de nuestros clientes y partners han manifestado su interés en aprovechar los datos de SoSafe para distintos fines en sus organizaciones, como:

Generación de informes: Automatización del proceso de extracción de datos de formación para crear informes personalizados adaptados a sus necesidades específicas.
Integración en sistemas internos: Las organizaciones suelen querer incorporar los datos de formación de SoSafe en sus sistemas internos de seguridad o de RRHH para obtener una visión completa de la formación de los empleados junto con otras métricas empresariales.
Creación de paneles de conocimiento: Puede combinar nuestros datos con cualquier otro dato al que tenga acceso para crear paneles personalizados que muestren el progreso de la formación e identifiquen las áreas que necesitan mejora.

Para los partners, esta API abre posibilidades adicionales:

Integración de los datos de formación de SoSafe en sus propias soluciones: Como partner, puede desarrollar integraciones que incorporen datos de formación en ciberseguridad en sus propios productos o servicios, ofreciendo funcionalidades de valor añadido a sus Clients.
Soluciones conjuntas: Combine los datos de E-Learning de SoSafe con otras herramientas o servicios para crear soluciones integrales de seguridad o formación para sus clientes.

Sin la API, solo podría interactuar manualmente con la interfaz de SoSafe para recopilar datos, lo que limitaba su capacidad de actuar sobre ellos y aprovecharlos de forma eficaz.

¿Qué es una API?

Una API, siglas de Application Programming Interface (interfaz de programación de aplicaciones), es una herramienta que permite que dos sistemas o programas distintos se comuniquen entre sí e intercambien información. Puede entenderse como un puente entre el software de su empresa y SoSafe. En lugar de iniciar sesión manualmente en SoSafe para obtener datos, la API permite que su sistema los recupere automáticamente cuando los necesite, otorgándole la capacidad de utilizarlos exactamente como su organización lo requiera.

Limitaciones actuales

Por el momento, la API se limita a los datos de E-Learning y Phishing Simulation.

Documentación técnica

La API REST de SoSafe proporciona acceso a datos de usuarios y de E-Learning de nuestra plataforma, lo que permite la integración en sus sistemas. Todos los datos se devuelven en formato JSON de forma predeterminada, lo que facilita su procesamiento y personalización. Al utilizar las APIs de SoSafe, acepta nuestras Condiciones del servicio.

Nuestras APIs utilizan URLs orientadas a recursos, métodos HTTP estándar y códigos de respuesta para la gestión de errores. Estas APIs están disponibles para los clientes Premium, con soporte para la integración y la resolución de incidencias.

A continuación encontrará información básica. Para consultar la documentación técnica completa, consulte la especificación OpenAPI.

Requisitos previos

Para utilizar el SoSafe API necesitará:

Un E-Learning de SoSafe activo y/o una Phishing Simulation activa
Acceso a la página de gestión de claves API del SoSafe Manager
- Si no tiene acceso a esta página, consulte con su persona de contacto de SoSafe si dispone del paquete necesario para utilizar las integraciones de Analytics
Conocimientos técnicos sobre el uso de APIs

URL base

Asegúrese de utilizar la URL base correcta en función de la ubicación de su cuenta al realizar solicitudes a la API. Por lo general, debería ser https://connect.sosafe.de.

Autenticación

Para acceder a la API de SoSafe, los usuarios deben autenticarse mediante un proceso en dos pasos que implica una clave API y un token de sesión.

Generar clave API: Obtenga su clave API desde el portal del Manager. Esta clave se utiliza para solicitar tokens de sesión, pero no para el acceso directo a la API. Asegúrese de seleccionar los ámbitos adecuados en función de las solicitudes de API que vaya a utilizar posteriormente.
Iniciar sesión para obtener el JSON Web Token (JWT): Envíe una solicitud POST a /auth/login con su clave API en la cabecera X-Api-Key. Una solicitud válida devuelve un token de sesión JWT de corta duración.
Realizar solicitudes a la API: Incluya el JWT en la cabecera Authorization: Bearer <jwt> para acceder a la API.
Renovación del token: Una vez que haya expirado, utilice de nuevo la clave API para obtener un nuevo token de sesión JWT.

Por motivos de seguridad, las solicitudes a la API deben realizarse a través de HTTPS. Las claves API comprometidas pueden revocarse en el portal.

Formato de respuesta

Las respuestas de la API de SoSafe tienen formato JSON. Todas las fechas y horas de las respuestas siguen el estándar UTC (Tiempo Universal Coordinado), lo que garantiza la coherencia entre las distintas zonas horarias.

Endpoint de usuarios

El endpoint de Users /users permite acceder a una lista de usuarios asociados a su cuenta y devuelve información relevante como el nombre, el correo electrónico, el nivel de usuario, el grupo, los atributos personalizados y el estado (habilitado/deshabilitado).

Ejemplos de casos de uso:

Obtener la lista de todos los usuarios

Recupere la lista completa de usuarios, incluidos atributos detallados como nombre, correo electrónico, nivel de usuario, grupo y campos personalizados.

Obtener la lista de usuarios específicos

Recupere datos de usuarios concretos con opciones de filtrado adicionales:

Filtrar por grupo: Devuelve los usuarios que pertenecen a un grupo determinado.

Filtrar por campaña de aprendizaje: Devuelve los usuarios que forman parte de una campaña de E-Learning específica.

Endpoints de E-Learning

Endpoint de campañas

El endpoint de campañas /campaigns/elearning permite acceder a la lista de campañas de E-Learning activas en su cuenta. Recibirá información como el nombre y las fechas de una campaña, así como su ID, lo que puede ser útil para filtrar datos de otros endpoints.

Endpoint de Analytics

El endpoint de E-Learning /analytics/elearning permite recuperar el progreso de los usuarios en relación con los módulos de formación y las campañas asignados. Una vez devueltos los datos, pueden filtrarse para extraer la información específica que se necesite.

Ejemplos de casos de uso

Obtener el progreso de E-Learning de todos los usuarios

Recupere los datos de progreso de todos los usuarios en todos los contenidos de E-Learning asignados.

Obtener el progreso de E-Learning de un usuario específico

Obtenga el progreso detallado de un usuario concreto.

Obtener el progreso de E-Learning de un grupo de usuarios

Recupere los datos de progreso de un grupo de usuarios determinado.

Obtener el progreso de E-Learning de todas las campañas

Obtenga informes de progreso de todas las campañas de E-Learning.

Obtener el progreso de E-Learning de una campaña específica

Recupere el progreso de una campaña de E-Learning concreta.

Obtener el progreso de E-Learning de un módulo específico

Obtenga el progreso detallado de un módulo de formación concreto.

Endpoints de Phishing Simulation

Campaigns

El endpoint de Phishing Simulation /phishing-simulation/campaigns permite recuperar una lista de las Phishing Simulations actuales y archivadas (también conocidas como campañas).

Los datos devueltos incluyen:

ID de campaña (que puede utilizarse para recuperar las Analytics de una campaña mediante el endpoint /phishing-simulation/analytics (véase más abajo))
Nombre de la campaña
Fecha de inicio y fin de la campaña
Estado de la campaña: WAITING, ACTIVE, FINISHED, PAUSED, INACTIVE, PENDING, ALLOWLISTING_PENDING, SCHEDULED
Versión de la campaña
Estado de archivo (true, false)
Disponibilidad de Analytics (true, false)

Consulte las especificaciones OpenAPI para obtener una descripción técnica de los datos y el formato correspondiente.

Analytics

El endpoint de Phishing Simulation /phishing-simulation/analytics permite recuperar datos detallados de la simulación de phishing. Los datos disponibles equivalen a los accesibles a través de la descarga de datos en Analytics. Esto significa que obtiene acceso a una lista de todos los correos electrónicos de phishing simulados enviados, con los siguientes atributos:

Nombre e ID de la plantilla
Asunto del correo electrónico
Nombre y apellidos del destinatario
Nombre del remitente
Idioma
Grupo de usuarios
Estado del correo, incluida la fecha de envío
Información de interacción (fechas de apertura, clic, interacción, aprendizaje, respuesta y notificación, si están disponibles)
Si se utilizó un agente de usuario móvil
Nombre del tenant y de la campaña

Puede utilizar estos datos como punto de partida para crear sus propios KPIs o replicar los KPIs de SoSafe. Para saber cómo se calculan estos últimos, consulte la sección https://support.sosafe.de/ProductDoc/analytics de nuestra Knowledge Base.