Una clave API de Cuenta de servicio te permite conectar servicios externos con PeopleForce y controlar a qué datos de los empleados y acciones a nivel de empresa pueden acceder a través de la API. A diferencia de una clave API de Compañía, el acceso de una Cuenta de servicio se gestiona mediante un rol específico en Roles y permisos.
🔑 Generar una clave API de Cuenta de servicio
Ve a Ajustes → Claves API.
Haz clic en + Nuevo.
Introduce un nombre para la clave.
En el campo Tipo, selecciona Cuenta de servicio.
Si es necesario, especifica las direcciones IP que pueden utilizar la clave.
Haz clic en Generar. Copia la clave API generada y guárdala en un lugar seguro. Por motivos de seguridad, PeopleForce no volverá a mostrar la clave completa una vez generada.
💡 Si Cuenta de servicio no está disponible como tipo de clave API, contacta con support@peopleforce.io para activar esta función.
👤 Crear un rol para la Cuenta de servicio
Después de generar la clave, crea un rol que determine a qué puede acceder.
Ve a Ajustes → Roles y permisos.
Haz clic en Nuevo rol y selecciona Cuenta de servicio.
Introduce el nombre del rol y, opcionalmente, una descripción.
En ¿A quién se le asigna este rol?, selecciona la clave API de Cuenta de servicio que has creado.
A continuación, configura los permisos del rol para determinar a qué puede acceder la Cuenta de servicio a través de la API.
🔐 Configurar el acceso a los datos de los empleados
Abre la pestaña Gente para definir a qué empleados y datos puede acceder la Cuenta de servicio.
En ¿A los datos de quién pueden acceder los miembros?, selecciona los empleados cuyos datos deben estar disponibles:
Personas específicas: utiliza condiciones para definir a qué empleados puede acceder la Cuenta de servicio.
Todos: permite el acceso a todos los empleados.
También puedes seleccionar Incluye empleados despedidos si necesitas incluirlos.
A continuación, configura los permisos para los datos de empleados necesarios. Según el permiso, puedes seleccionar:
Ninguna: sin acceso;
Ver: acceso de lectura;
Editar: permiso para realizar cambios.
Si el rol no incluye a un empleado concreto, este no se devolverá a través de la API. Si el rol no tiene acceso a un campo específico, dicho campo no aparecerá en la respuesta de la API.
🏢 Configurar los permisos de la empresa
Utiliza la pestaña Compañía para conceder acceso a las funciones a nivel de empresa.
Activa los permisos de gestión necesarios según las acciones que deba realizar la integración, por ejemplo, al trabajar con datos generales de la empresa como departamentos o ubicaciones.
Concede únicamente los permisos que necesite tu integración.
🔌 Utilizar la clave con API v4
Las claves de Cuenta de servicio se utilizan con PeopleForce API v4.
Pasa la clave generada en el encabezado de la solicitud:
X-API-KEY
Actualmente, API v4 no incluye todos los endpoints disponibles en API v3. Antes de configurar una integración, comprueba que los endpoints necesarios estén disponibles en la referencia de API v4.
📚 Para obtener más información sobre la autenticación, consulta Autenticación de API v4.