Usuários, Papéis e Permissões

O SnapOtter já vem com três papéis integrados, 17 permissões granulares e suporte a papéis personalizados com controle de acesso por ferramenta opcional. Esta página cobre todo o modelo de autorização, escopo de chaves de API, gerenciamento de times e log de auditoria.

Páginas relacionadas

OIDC / SSO | SAML SSO | Provisionamento SCIM | Segurança e Hardening

Usuários

Criando usuários

Os administradores podem criar usuários pelo painel de administração ou pelo endpoint POST /api/auth/register. Cada usuário tem um nome de usuário, um papel, uma atribuição de time e um endereço de e-mail opcional.

Admin padrão

Na primeira inicialização, o SnapOtter cria uma conta de admin padrão. As credenciais vêm de variáveis de ambiente:

Variável	Padrão	Descrição
DEFAULT_USERNAME	admin	Nome de usuário da conta de admin inicial
DEFAULT_PASSWORD	admin	Senha da conta de admin inicial

O admin padrão é obrigado a alterar a senha no primeiro login.

Provedores de autenticação

Os usuários podem se autenticar por vários métodos:

• Local - nome de usuário e senha armazenados no banco de dados do SnapOtter
• OIDC - qualquer provedor OpenID Connect (veja OIDC / SSO)
• SAML - provedores de identidade SAML 2.0 (veja SAML SSO)
• SCIM - provisionamento automatizado a partir de um provedor de identidade (veja Provisionamento SCIM)

Desativando a autenticação

Defina AUTH_ENABLED=false para desativar a autenticação por completo. Nesse modo, um usuário anônimo sintético com o papel admin é usado para todas as requisições. Nenhum login é necessário.

WARNING

Desativar a autenticação concede acesso total de admin a qualquer pessoa que consiga alcançar a instância. Use isso apenas em ambientes confiáveis.

Papéis integrados

O SnapOtter inclui três papéis integrados. Eles não podem ser modificados nem excluídos.

Admin

Todas as 17 permissões. Controle total sobre a instância.

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 permissões. Pode usar todas as ferramentas e gerenciar todos os arquivos e pipelines, mas não pode acessar funções de administração.

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

User

5 permissões. Pode usar ferramentas e gerenciar os próprios recursos.

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

Referência de permissões

Permissão	Descrição
tools:use	Usar qualquer ferramenta de processamento
files:own	Ver e gerenciar os próprios arquivos
files:all	Ver e gerenciar os arquivos de todos os usuários
apikeys:own	Criar e gerenciar as próprias chaves de API
apikeys:all	Ver as chaves de API de todos os usuários
pipelines:own	Criar e gerenciar os próprios pipelines
pipelines:all	Ver e gerenciar os pipelines de todos os usuários
settings:read	Ver as configurações da instância
settings:write	Modificar as configurações da instância
users:manage	Criar, atualizar e excluir contas de usuário
teams:manage	Criar, atualizar e excluir times
features:manage	Instalar e gerenciar bundles de recursos de IA
system:health	Acessar os endpoints de health e readiness
audit:read	Ver o log de auditoria e listar papéis
compliance:manage	Gerenciar o ciclo de vida de GDPR e recursos de conformidade
webhooks:manage	Configurar webhooks de saída
security:manage	Gerenciar configurações de segurança (lista de IPs permitidos, imposição de SSO)

Papéis personalizados

Os administradores com a permissão security:manage podem criar papéis personalizados pelo painel de administração ou pela API de papéis. Listar papéis requer audit:read.

Criando um papel 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"]
  }'

Os nomes de papéis devem ter de 2 a 30 caracteres, alfanuméricos em minúsculas, com hifens e underscores.

Permissões reservadas ao admin

Três permissões são reservadas aos papéis integrados e não podem ser atribuídas a papéis personalizados:

• compliance:manage
• webhooks:manage
• security:manage

A API de papéis rejeita qualquer requisição que inclua essas permissões. Somente o papel integrado admin tem acesso a elas.

Permissões no nível de ferramenta

Papéis personalizados podem, opcionalmente, restringir quais ferramentas os usuários podem acessar. Dois modos estão disponíveis:

Modo	Comportamento	Requisito de licença
category	Restringir por modalidade (imagem, vídeo, áudio, documento, arquivo)	Nenhum (grátis)
tool	Restringir por ID individual de ferramenta	Requer o recurso enterprise per_tool_permissions

Quando o modo tool está definido mas o recurso enterprise não está disponível, o SnapOtter degrada de forma controlada e permite o acesso a todas as ferramentas.

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

Excluindo um papel personalizado

Quando um papel personalizado é excluído, todos os usuários atribuídos a ele são automaticamente reatribuídos ao papel user.

Times

Os times agrupam usuários para gerenciamento de armazenamento e retenção. Um time Default é criado na primeira inicialização.

Campo	Tipo	Descrição
name	string	Nome único do time (1-50 caracteres)
storageQuota	number	Limite de armazenamento por time em bytes (funciona sem enterprise)
retentionHours	number	Excluir saídas automaticamente após esta quantidade de horas (requer team_retention_overrides, enterprise)
legalHold	boolean	Impedir a exclusão automática dos arquivos dos membros do time (requer legal_hold, enterprise)

INFO

O time Default não pode ser excluído. Times que ainda têm membros não podem ser excluídos. Reatribua os membros primeiro.

Chaves de API

Os usuários podem gerar chaves de API para acesso programático. Cada chave usa o prefixo si_ e é mostrada apenas uma vez, no momento da criação.

Permissões com escopo

As chaves de API podem, opcionalmente, carregar um array permissions. Quando definido, as permissões efetivas de uma requisição são a interseção das permissões do papel do usuário com as permissões escopadas da chave. Isso significa que uma chave de API nunca pode escalar além das próprias permissões do usuário.

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"
  }'

Expiração

As chaves aceitam um timestamp expiresAt opcional. Chaves expiradas são rejeitadas no momento da autenticação.

Log de auditoria

O SnapOtter registra eventos relevantes para segurança em um log de auditoria estruturado, armazenado na tabela audit_log do banco de dados.

Visualizando o log de auditoria

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

Requer a permissão audit:read. Suporta paginação (page, limit) e filtros (action, ip, from, to).

Auditoria de operação de ferramentas

WARNING

Eventos TOOL_EXECUTED não são registrados por padrão. Eles são opt-in por meio de um de dois caminhos:

1. Definir a configuração de admin auditToolOperations como true.
2. Ter uma licença ativa com o recurso audit_export (disponível nos planos team e enterprise).

Sem uma dessas condições, execuções individuais de ferramentas não são registradas no log de auditoria.

Exportando

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

Requer a permissão audit:read e o recurso enterprise audit_export (disponível nos planos team e enterprise). Suporta os formatos CSV e JSON, filtrados por action, actorId, targetType, targetId, from e to.

Assinatura resistente a adulteração

Quando habilitado, cada entrada do log de auditoria é assinada com um HMAC derivado de DATA_ENCRYPTION_KEY. Isso requer:

1. Definir DATA_ENCRYPTION_KEY no seu ambiente.
2. Habilitar a configuração de admin tamperResistantAudit.
3. Uma licença enterprise com o recurso tamper_resistant_audit.

Retenção

Defina AUDIT_RETENTION_DAYS para eliminar automaticamente entradas antigas. O padrão é 0, o que significa que as entradas são mantidas indefinidamente.

Referência de eventos

Evento	Categoria
LOGIN_SUCCESS, LOGIN_FAILED	Autenticação
OIDC_LOGIN_SUCCESS, OIDC_LOGIN_FAILED	Autenticação
SAML_LOGIN_SUCCESS, SAML_LOGIN_FAILED	Autenticação
LOGOUT	Autenticação
USER_CREATED, USER_UPDATED, USER_DELETED	Gerenciamento de usuários
PASSWORD_CHANGED, PASSWORD_RESET	Gerenciamento de usuários
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	Papéis
API_KEY_CREATED, API_KEY_DELETED	Chaves de API
SETTINGS_UPDATED, IP_ALLOWLIST_UPDATED	Configurações
FILE_UPLOADED, FILE_DELETED	Arquivos
TOOL_EXECUTED	Ferramentas (opt-in)
SCIM_USER_PROVISIONED, SCIM_USER_UPDATED, SCIM_USER_DEPROVISIONED	SCIM
SCIM_GROUP_SYNCED	SCIM
LEGAL_HOLD_APPLIED, LEGAL_HOLD_RELEASED	Conformidade
GDPR_EXPORT_INITIATED, GDPR_USER_PURGED, GDPR_TEAM_PURGED	Conformidade
CONFIG_EXPORTED, CONFIG_IMPORTED	Configuração

Gerenciamento de sessões

As sessões são baseadas em cookies, controladas por SESSION_DURATION_HOURS (padrão: 168 horas / 7 dias).

Mudanças de papel invalidam sessões

Quando um admin altera o papel de um usuário, todas as sessões ativas desse usuário são excluídas. O usuário precisa fazer login novamente para receber suas novas permissões.

Proteções de segurança

• Proteção do último admin: o último admin restante não pode ser rebaixado para um papel inferior. A API retorna um erro se você tentar.
• Prevenção de autoexclusão: os administradores não podem excluir a própria conta pela API.