# Usuarios y permisos (/docs/configuration/access)

Aquí administras quién entra a la plataforma y qué servicios externos se conectan a tu organización. Los usuarios y los roles están en **Configuración → Usuarios y permisos**; las API keys y las integraciones, en el grupo **Plataforma** del mismo menú.

Los empleados que solo consultan su información en el portal de colaborador no necesitan ser usuarios: entran con el correo o el teléfono registrado en su expediente.

## Usuarios [#usuarios]

**Configuración → Usuarios y permisos → Usuarios** muestra a los usuarios de la organización con su **Rol**, si es **Propietario** y su **Fecha de ingreso**. La pestaña **Invitaciones** muestra las invitaciones que todavía no se aceptan, con su **Estatus** (**Pendiente** o **Expirada**) y la fecha en que **Expira**.

![Lista de usuarios de la organización](/images/guides/configuration/members.webp)

### Invitar a un usuario [#invitar]

1. Haz clic en **Invitar usuario**. Se abre la página de invitación.
2. Escribe su **Correo electrónico**.
3. Si quieres que sea **Propietario de la organización**, marca la casilla. Solo un propietario puede otorgarlo.
4. En **Acceso**, elige de dónde vienen sus permisos:
   * **Rol asignado**: elige un **Rol**. Abajo se muestran los permisos que concede ese rol.
   * **Permisos propios**: define los permisos de esta persona, módulo por módulo, igual que en un rol. Si antes elegiste un rol, se parte de sus permisos.
5. Haz clic en **Enviar invitación**.

![Página para invitar a un usuario](/images/guides/configuration/invite-member.webp)

La persona recibe un correo con un enlace para unirse a la organización:

* Si todavía no tiene cuenta, la crea en esa misma página.
* Si ya tiene cuenta, inicia sesión ahí mismo con el correo invitado y la invitación se acepta al entrar.
* Si tiene abierta una sesión con otro correo, la página le ofrece **Cambiar cuenta** para continuar con el correo invitado.

Al aceptar, ve una confirmación con la organización y el acceso que recibió, y entra con **Entrar**.

La invitación vence a las 48 horas. En la pestaña **Invitaciones**, el menú de opciones de cada invitación permite:

* **Reenviar invitación**: envía un enlace nuevo con 48 horas más de vigencia. El enlace anterior deja de funcionar.
* **Editar invitación**: cambia el rol, los permisos propios o si será propietario. No se envía un correo nuevo y el enlace sigue funcionando. El correo no se puede cambiar; para invitar otro correo, cancela esta invitación y envía una nueva.
* **Cancelar invitación**: el enlace deja de funcionar.

Desde el menú de opciones de un usuario puedes **Editar** su nombre, su acceso y si es propietario, o **Eliminar** su acceso a la organización. El correo y el teléfono los administra cada persona desde su cuenta. No puedes eliminarte a ti mismo.

## Roles y permisos [#roles]

Un rol es un conjunto de permisos que se asigna a los usuarios. Se administran en **Configuración → Usuarios y permisos → Permisos**. La lista muestra el **Nombre** de cada rol con su descripción, cuántos **permisos** concede y cuántos **Usuarios** lo tienen.

La organización empieza con cuatro roles, que puedes editar para ajustarlos a tu equipo:

* **Administrador**: todos los permisos, incluidos los usuarios, los roles y las integraciones.
* **Nómina**: configura y opera la nómina de principio a fin: calcula, cierra y timbra. También administra los empleados, sus créditos y sus incidencias. No administra usuarios ni integraciones.
* **Recursos humanos**: administra los empleados, la estructura organizacional, la asistencia, las incidencias, los horarios y las vacaciones y permisos, que también autoriza. Ve la nómina, pero no la calcula, no la cierra ni la timbra.
* **Consulta**: puede ver todos los módulos, excepto los sueldos.

![Lista de roles de la organización](/images/guides/configuration/roles.webp)

Para crear un rol, haz clic en **Crear rol** y escribe su **Nombre** y, si quieres, una **Descripción**. Desde el menú de opciones de un rol puedes **Editar** o **Eliminar**. Un rol no se puede eliminar mientras tenga usuarios asignados o invitaciones pendientes: reasigna a esos usuarios y edita o cancela esas invitaciones primero.

Los permisos se organizan por sección: **Capital Humano**, **Organización**, **Asistencia e incidencias**, **Nómina**, **Usuarios y permisos** y **Desarrolladores**. Elige una sección en la barra de secciones y, para cada módulo, define tres cosas:

* **Nivel**: **Ninguno**, **Ver** o **Administrar**. Administrar incluye ver.
* **Capacidades aparte**: algunas acciones se conceden por separado con una casilla, como **Ejecutar** y **Cerrar periodo** en las corridas de nómina, o **Autorizar** en vacaciones y permisos. Se activan cuando el módulo tiene al menos **Ver**.
* **Alcance**: **Toda la organización** o, en los módulos que lo permiten, **Su razón social**, algunas **Razones sociales** o algunas **Unidades organizacionales**. Si acotas un permiso, elige sus razones sociales o unidades antes de guardar.

![Editor de permisos de un rol, con niveles por módulo y alcance](/images/guides/configuration/role-form.webp)

Los botones **Ver**, **Administrar** y **Limpiar** aplican ese nivel a todos los módulos de la sección que tienes abierta. El ícono de información junto a cada módulo explica qué cubre.

**Próximamente.** Hoy los roles solo determinan qué indicadores ve cada usuario en el **Dashboard**. En el resto de la plataforma, cualquier usuario de la organización puede ver y hacer todo, sin importar su rol. Los roles que configures se aplicarán a cada módulo conforme se active el control de permisos.

## API keys [#api-keys]

Una API key permite que un servicio externo, como un reloj checador o tu sistema contable, se conecte a la organización a través de la API. Se administran en **Configuración → API keys**.

1. Haz clic en **Crear API key**.
2. Escribe un **Nombre** que identifique el servicio que la usará.
3. Elige el **Miembro** al que queda asociada.
4. Enciende los permisos que necesita. Están agrupados por módulo, por ejemplo **Empleados** o **Departamentos**; **Seleccionar todo** y **Seleccionar todos** encienden todos los permisos, o todos los de un módulo.
5. Si quieres que la llave venza, elige un **Vencimiento** de 30, 90, 180 o 365 días. Sin vencimiento, la llave sigue vigente hasta que la revoques o la elimines.
6. Haz clic en **Crear API key**.

![Lista de API keys de la organización](/images/guides/configuration/api-keys.webp)

![Formulario para crear una API key con sus permisos](/images/guides/configuration/api-key-form.webp)

**La llave solo se muestra una vez.** Al crearla, cópiala y guárdala en un lugar seguro antes de cerrar el diálogo. Después ya no se puede volver a ver; si la pierdes, elimínala y crea otra.

Da a cada llave solo los permisos que el servicio necesita. Desde el menú de opciones de la llave puedes **Editar** sus permisos, **Revocar** la llave o **Eliminarla**. Al revocarla, los servicios que la usan dejan de tener acceso de inmediato y la llave se conserva en la lista como **Revocada**. Al eliminarla, también pierden acceso y la llave desaparece de la lista; no se puede deshacer.

La columna **Estado** indica si la llave está **Activa**, **Por vencer** (le quedan 7 días o menos), **En reemplazo**, **Vencida** o **Revocada**. Los dueños de la organización reciben un correo cuando a una llave le quedan 7 días y 1 día.

La documentación técnica de la API está en **Desarrolladores**, en el mismo menú.

## Integraciones [#integraciones]

En **Configuración → Integraciones** registras los servicios externos que se conectan a tu organización, con un **Nombre** y una **Descripción**. Haz clic en **Crear integración** para agregar una.

![Pantalla de integraciones sin registros](/images/guides/configuration/integrations.webp)

Al abrir una integración, la parte superior muestra su **salud**: el **Estatus** según las llamadas de la última hora, el porcentaje de errores, la última llamada correcta y las llaves que han trabajado en las últimas 24 horas. Las llamadas incluyen los envíos de webhooks. El estatus es **Fallando** cuando la mitad o más de las llamadas de la última hora terminan en error, **Con fallas** desde el 10 %, **Operando** por debajo de eso y **Sin actividad** si no hubo llamadas. Las llamadas a la API rechazadas por falta de permiso se muestran aparte y nunca marcan la integración como fallando. En un webhook, cualquier respuesta fuera de 2xx o la falta de respuesta cuenta como error. El mismo estatus aparece en la lista de integraciones.

La pestaña **API Keys** muestra las llaves emitidas para la integración, la pestaña **Permisos** los permisos que se le otorgaron, la pestaña **Webhooks** las direcciones a las que avisa y la pestaña **Logs** el historial de sus llamadas y de cada intento de envío de sus webhooks, marcados como **Webhook**.

**Avisa a otro sistema cuando algo pasa.** En la pestaña **Webhooks**, haz clic en **Crear webhook**, escribe la **URL** del sistema que recibe el aviso y marca los **Eventos**: empleado creado, actualizado o dado de baja; periodo abierto, calculado o cerrado; recibo timbrado o con error de timbrado, y solicitud de tiempo libre aprobada. La URL debe empezar con `https://` y apuntar a una dirección pública. El campo **Activo** viene encendido; si lo apagas, el webhook se guarda en pausa. El **Secreto de firma** se muestra una sola vez: guárdalo en el sistema que recibe el aviso para que compruebe que viene de la plataforma.

La integración solo recibe los eventos que puede consultar con sus permisos, y el formulario marca los eventos para los que no tiene permiso o que solo recibe para algunas razones sociales. Cada fila muestra su última entrega: **Entregado**, **Reintentando**, **Fallido** o **No enviado**. Si la dirección falla, el envío se reintenta a 1 minuto, 5 minutos, 30 minutos, 2 horas y 6 horas; al sexto intento fallido queda en **Fallido**. Desde el menú de la fila puedes **Editar**, **Pausar** o **Eliminar** el webhook; al editarlo también puedes pausarlo o reactivarlo con el campo **Activo**. Mientras está en pausa no recibe eventos nuevos y sus avisos pendientes esperan hasta que haces clic en **Reactivar**; un envío que iba a reintentarse se muestra **En espera**. Si dejas de marcar un evento, sus avisos pendientes se descartan. Al eliminarlo, sus avisos pendientes se descartan y los intentos ya enviados siguen en **Logs**. Lo que el sistema receptor necesita saber está en [Webhooks](/docs/developers/webhooks).

**Rota una llave sin interrumpir el servicio.** En el menú de opciones de una llave de integración vigente, elige **Rotar**. Se crea una llave nueva con los mismos permisos y la misma vigencia que tenía la anterior, y se muestra una sola vez. La llave anterior sigue funcionando durante el **Periodo de transición** que elijas (1, 7 o 30 días), tiempo en el que actualizas el servicio con la llave nueva. Pasado ese periodo la anterior deja de funcionar; puedes **Revocarla** antes si ya no la necesitas. Una llave solo se puede rotar una vez.