Usuarios, roles y permisos

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.

Páginas relacionadas

OIDC / SSO | SAML SSO | Aprovisionamiento SCIM | Seguridad y fortalecimiento

Usuarios

Crear usuarios

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

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

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)
• SAML: proveedores de identidad SAML 2.0 (consulta SAML SSO)
• SCIM: aprovisionamiento automatizado desde un proveedor de identidad (consulta Aprovisionamiento SCIM)

Desactivar la autenticación

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

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

Administrador

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

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

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

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

Referencia de permisos

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

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

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

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

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.

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

Eliminar un rol personalizado

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

Equipos

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

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

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.

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

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

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

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

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

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

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

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

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

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

Los cambios de rol invalidan las sesiones

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

• 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.