SnapOtter/apps/docs/es/guide/users-roles.md

---
description: "Gestiona usuarios, roles integrados y personalizados, permisos, claves de API, equipos, sesiones y el registro de auditoría en SnapOtter."
i18n_source_hash: 5e28af686c96
i18n_provenance: human
i18n_output_hash: a2ceae4b73a7
---

# Usuarios, roles y permisos {#users-roles-permissions}

SnapOtter incluye tres roles integrados, 17 permisos granulares y compatibilidad con roles personalizados con control de acceso opcional por herramienta. Esta página cubre el modelo de autorización completo, el alcance de las claves de API, la gestión de equipos y el registro de auditoría.

::: tip Páginas relacionadas
[OIDC / SSO](/es/guide/oidc) | [SAML SSO](/es/guide/saml) | [Aprovisionamiento SCIM](/es/guide/scim) | [Seguridad y fortalecimiento](/es/guide/security)
:::

## Usuarios {#users}

### Crear usuarios {#creating-users}

Los administradores pueden crear usuarios a través del panel de administración o el endpoint `POST /api/auth/register`. Cada usuario tiene un nombre de usuario, un rol, una asignación de equipo y una dirección de correo electrónico opcional.

### Administrador predeterminado {#default-admin}

En el primer arranque, SnapOtter crea una cuenta de administrador predeterminada. Las credenciales provienen de variables de entorno:

| Variable | Predeterminado | Descripción |
|---|---|---|
| `DEFAULT_USERNAME` | `admin` | Nombre de usuario de la cuenta de administrador inicial |
| `DEFAULT_PASSWORD` | `admin` | Contraseña de la cuenta de administrador inicial |

Se requiere que el administrador predeterminado cambie su contraseña en el primer inicio de sesión.

### Proveedores de autenticación {#authentication-providers}

Los usuarios pueden autenticarse mediante varios métodos:

- **Local**: nombre de usuario y contraseña almacenados en la base de datos de SnapOtter
- **OIDC**: cualquier proveedor de OpenID Connect (consulta [OIDC / SSO](/es/guide/oidc))
- **SAML**: proveedores de identidad SAML 2.0 (consulta [SAML SSO](/es/guide/saml))
- **SCIM**: aprovisionamiento automatizado desde un proveedor de identidad (consulta [Aprovisionamiento SCIM](/es/guide/scim))

### Desactivar la autenticación {#disabling-authentication}

Establece `AUTH_ENABLED=false` para desactivar por completo la autenticación. En este modo se usa un usuario anónimo sintético con el rol `admin` para todas las solicitudes. No se requiere inicio de sesión.

::: warning 
Desactivar la autenticación otorga acceso total de administrador a cualquiera que pueda alcanzar la instancia. Úsalo solo en entornos de confianza.
:::

## Roles integrados {#built-in-roles}

SnapOtter incluye tres roles integrados. No se pueden modificar ni eliminar.

### Administrador {#admin}

Los 17 permisos. Control total sobre la instancia.

`tools:use` `files:own` `files:all` `apikeys:own` `apikeys:all` `pipelines:own` `pipelines:all` `settings:read` `settings:write` `users:manage` `teams:manage` `features:manage` `system:health` `audit:read` `compliance:manage` `webhooks:manage` `security:manage`

### Editor {#editor}

7 permisos. Puede usar todas las herramientas y gestionar todos los archivos y pipelines, pero no puede acceder a las funciones de administración.

`tools:use` `files:own` `files:all` `apikeys:own` `pipelines:own` `pipelines:all` `settings:read`

### Usuario {#user}

5 permisos. Puede usar herramientas y gestionar sus propios recursos.

`tools:use` `files:own` `apikeys:own` `pipelines:own` `settings:read`

## Referencia de permisos {#permissions-reference}

| Permiso | Descripción |
|---|---|
| `tools:use` | Usar cualquier herramienta de procesamiento |
| `files:own` | Ver y gestionar los archivos propios |
| `files:all` | Ver y gestionar los archivos de todos los usuarios |
| `apikeys:own` | Crear y gestionar las claves de API propias |
| `apikeys:all` | Ver las claves de API de todos los usuarios |
| `pipelines:own` | Crear y gestionar los pipelines propios |
| `pipelines:all` | Ver y gestionar los pipelines de todos los usuarios |
| `settings:read` | Ver la configuración de la instancia |
| `settings:write` | Modificar la configuración de la instancia |
| `users:manage` | Crear, actualizar y eliminar cuentas de usuario |
| `teams:manage` | Crear, actualizar y eliminar equipos |
| `features:manage` | Instalar y gestionar bundles de funciones de IA |
| `system:health` | Acceder a los endpoints de estado y disponibilidad |
| `audit:read` | Ver el registro de auditoría y listar roles |
| `compliance:manage` | Gestionar el ciclo de vida de RGPD y las funciones de cumplimiento |
| `webhooks:manage` | Configurar webhooks salientes |
| `security:manage` | Gestionar la configuración de seguridad (lista de IP permitidas, imposición de SSO) |

## Roles personalizados {#custom-roles}

Los administradores con el permiso `security:manage` pueden crear roles personalizados a través del panel de administración o la API de roles. Listar roles requiere `audit:read`.

### Crear un rol personalizado {#creating-a-custom-role}

```bash
curl -X POST http://localhost:1349/api/v1/roles \
  -H "Authorization: Bearer si_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "reviewer",
    "description": "Can use tools and view all files",
    "permissions": ["tools:use", "files:own", "files:all", "settings:read"]
  }'
```

Los nombres de rol deben tener entre 2 y 30 caracteres, alfanuméricos en minúscula con guiones y guiones bajos.

### Permisos reservados para administradores {#admin-reserved-permissions}

Tres permisos están reservados para los roles integrados y no pueden asignarse a roles personalizados:

- `compliance:manage`
- `webhooks:manage`
- `security:manage`

La API de roles rechaza cualquier solicitud que incluya estos permisos. Solo el rol integrado `admin` tiene acceso a ellos.

### Permisos a nivel de herramienta {#tool-level-permissions}

Los roles personalizados pueden restringir opcionalmente a qué herramientas pueden acceder los usuarios. Hay dos modos disponibles:

| Modo | Comportamiento | Requisito de licencia |
|---|---|---|
| `category` | Restringir por modalidad (imagen, video, audio, documento, archivo) | Ninguno (gratis) |
| `tool` | Restringir por ID de herramienta individual | Requiere la función empresarial `per_tool_permissions` |

Cuando el modo `tool` está establecido pero la función empresarial no está disponible, SnapOtter se degrada de forma controlada y permite el acceso a todas las herramientas.

```json
{
  "name": "image-only",
  "permissions": ["tools:use", "files:own"],
  "toolPermissions": {
    "mode": "category",
    "allowed": ["image"]
  }
}
```

### Eliminar un rol personalizado {#deleting-a-custom-role}

Cuando se elimina un rol personalizado, todos los usuarios asignados a él se reasignan automáticamente al rol `user`.

## Equipos {#teams}

Los equipos agrupan usuarios para la gestión de almacenamiento y retención. Se crea un equipo `Default` en el primer arranque.

| Campo | Tipo | Descripción |
|---|---|---|
| `name` | cadena | Nombre de equipo único (1-50 caracteres) |
| `storageQuota` | número | Límite de almacenamiento por equipo en bytes (funciona sin la edición empresarial) |
| `retentionHours` | número | Eliminar automáticamente las salidas tras esta cantidad de horas (requiere `team_retention_overrides`, empresarial) |
| `legalHold` | booleano | Impedir la eliminación automática de los archivos de los miembros del equipo (requiere `legal_hold`, empresarial) |

::: info 
El equipo `Default` no se puede eliminar. Los equipos que aún tienen miembros no se pueden eliminar. Reasigna primero a los miembros.
:::

## Claves de API {#api-keys}

Los usuarios pueden generar claves de API para el acceso programático. Cada clave usa el prefijo `si_` y se muestra una sola vez en el momento de la creación.

### Permisos con alcance {#scoped-permissions}

Las claves de API pueden llevar opcionalmente un array `permissions`. Cuando se establece, los permisos efectivos de una solicitud son la **intersección** de los permisos del rol del usuario y los permisos con alcance de la clave. Esto significa que una clave de API nunca puede escalar más allá de los propios permisos del usuario.

```bash
curl -X POST http://localhost:1349/api/v1/api-keys \
  -H "Authorization: Bearer si_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI pipeline key",
    "permissions": ["tools:use", "files:own"],
    "expiresAt": "2027-01-01T00:00:00Z"
  }'
```

### Caducidad {#expiration}

Las claves aceptan una marca de tiempo `expiresAt` opcional. Las claves caducadas se rechazan en el momento de la autenticación.

## Registro de auditoría {#audit-log}

SnapOtter registra los eventos relevantes para la seguridad en un registro de auditoría estructurado, almacenado en la tabla de base de datos `audit_log`.

### Ver el registro de auditoría {#viewing-the-audit-log}

```
GET /api/v1/audit-log?page=1&limit=50&action=LOGIN_FAILED&from=2026-01-01T00:00:00Z&to=2026-12-31T23:59:59Z
```

Requiere el permiso `audit:read`. Admite paginación (`page`, `limit`) y filtros (`action`, `ip`, `from`, `to`).

### Auditoría de operaciones de herramientas {#tool-operation-auditing}

::: warning 
Los eventos `TOOL_EXECUTED` **no** se registran de forma predeterminada. Son de participación voluntaria mediante cualquiera de dos vías:

1. Establecer la configuración de administrador `auditToolOperations` en `true`.
2. Tener una licencia activa con la función `audit_export` (disponible tanto en los planes team como enterprise).

Sin una de estas, las ejecuciones individuales de herramientas no se registran en el registro de auditoría.
:::

### Exportar {#exporting}

```
GET /api/v1/enterprise/audit/export?format=csv&from=2026-01-01T00:00:00Z
```

Requiere el permiso `audit:read` y la función empresarial `audit_export` (disponible tanto en los planes team como enterprise). Admite los formatos CSV y JSON, filtrados por `action`, `actorId`, `targetType`, `targetId`, `from` y `to`.

### Firma resistente a la manipulación {#tamper-resistant-signing}

Cuando está habilitado, cada entrada del registro de auditoría se firma con un HMAC derivado de `DATA_ENCRYPTION_KEY`. Esto requiere:

1. Establecer `DATA_ENCRYPTION_KEY` en tu entorno.
2. Habilitar la configuración de administrador `tamperResistantAudit`.
3. Una licencia empresarial con la función `tamper_resistant_audit`.

### Retención {#retention}

Establece `AUDIT_RETENTION_DAYS` para purgar automáticamente las entradas antiguas. El valor predeterminado es `0`, lo que significa que las entradas se conservan indefinidamente.

### Referencia de eventos {#event-reference}

| Evento | Categoría |
|---|---|
| `LOGIN_SUCCESS`, `LOGIN_FAILED` | Autenticación |
| `OIDC_LOGIN_SUCCESS`, `OIDC_LOGIN_FAILED` | Autenticación |
| `SAML_LOGIN_SUCCESS`, `SAML_LOGIN_FAILED` | Autenticación |
| `LOGOUT` | Autenticación |
| `USER_CREATED`, `USER_UPDATED`, `USER_DELETED` | Gestión de usuarios |
| `PASSWORD_CHANGED`, `PASSWORD_RESET` | Gestión de usuarios |
| `MFA_ENROLLED`, `MFA_DISABLED`, `MFA_VERIFIED`, `MFA_VERIFY_FAILED` | MFA |
| `MFA_CHALLENGE_ISSUED`, `MFA_RECOVERY_USED`, `MFA_RESET` | MFA |
| `ROLE_CREATED`, `ROLE_UPDATED`, `ROLE_DELETED` | Roles |
| `API_KEY_CREATED`, `API_KEY_DELETED` | Claves de API |
| `SETTINGS_UPDATED`, `IP_ALLOWLIST_UPDATED` | Configuración |
| `FILE_UPLOADED`, `FILE_DELETED` | Archivos |
| `TOOL_EXECUTED` | Herramientas (participación voluntaria) |
| `SCIM_USER_PROVISIONED`, `SCIM_USER_UPDATED`, `SCIM_USER_DEPROVISIONED` | SCIM |
| `SCIM_GROUP_SYNCED` | SCIM |
| `LEGAL_HOLD_APPLIED`, `LEGAL_HOLD_RELEASED` | Cumplimiento |
| `GDPR_EXPORT_INITIATED`, `GDPR_USER_PURGED`, `GDPR_TEAM_PURGED` | Cumplimiento |
| `CONFIG_EXPORTED`, `CONFIG_IMPORTED` | Configuración |

## Gestión de sesiones {#session-management}

Las sesiones se basan en cookies, controladas por `SESSION_DURATION_HOURS` (predeterminado: 168 horas / 7 días).

### Los cambios de rol invalidan las sesiones {#role-changes-invalidate-sessions}

Cuando un administrador cambia el rol de un usuario, todas las sesiones activas de ese usuario se eliminan. El usuario debe iniciar sesión de nuevo para adoptar sus nuevos permisos.

### Salvaguardas {#safety-guards}

- **Protección del último administrador**: el último administrador que queda no puede ser degradado a un rol inferior. La API devuelve un error si lo intentas.
- **Prevención de autoeliminación**: los administradores no pueden eliminar su propia cuenta a través de la API.