SnapOtter/apps/docs/pt-BR/guide/users-roles.md

description, i18n_source_hash, i18n_provenance, i18n_output_hash, i18n_hash_version

description	i18n_source_hash	i18n_provenance	i18n_output_hash	i18n_hash_version
Gerencie usuários, papéis integrados e personalizados, permissões, chaves de API, times, sessões e o log de auditoria no SnapOtter.	bea8955f3aff	human	4146f4acdfc0	2

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.

::: tip 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 e gerenciar contas de usuário dentro dos limites de autoridade do ator
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 e os recursos de conformidade do GDPR; operações destrutivas do usuário permanecem limitadas pela autoridade
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.

Limites de administração delegada

Todas as 17 permissões podem ser delegadas por meio de funções personalizadas, mas uma permissão administrativa não torna essa função equivalente à função admin integrada. Mutações de usuário autorizadas por users:manage, operações destrutivas autorizadas por compliance:manage e gerenciamento de função personalizada autorizada por security:manage são limitadas pela autoridade atual do ator:

• As funções integradas seguem admin > editor > user; as funções personalizadas estão abaixo das funções integradas.
• As permissões do alvo devem estar contidas nas permissões efetivas do ator. Uma chave de API com escopo definido, portanto, não pode exercer permissões omitidas de seu escopo.
• O acesso à ferramenta de uma função alvo deve ser contido pelo acesso à ferramenta do próprio ator.
• Uma conta desativada é verificada em relação à sua função original quando essa função é registrada como disabled:<original-role>.
• A exclusão de uma função personalizada também requer autoridade para atribuir o substituto user integrado; membros desabilitados permanecem desabilitados como disabled:user.

As credenciais e a configuração globais são mais rigorosas: a emissão ou revogação do token SCIM e a importação da configuração da instância exigem a função admin integrada com autoridade administrativa completa e efetiva.

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.