# Usuários, Papéis e Permissões {#users-roles-permissions}
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.
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 {#default-admin}
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 {#authentication-providers}
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
- **SCIM** - provisionamento automatizado a partir de um provedor de identidade (veja [Provisionamento SCIM](/pt-BR/guide/scim))
### Desativando a autenticação {#disabling-authentication}
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 {#built-in-roles}
O SnapOtter inclui três papéis integrados. Eles não podem ser modificados nem excluídos.
### Admin {#admin}
Todas as 17 permissões. Controle total sobre a instância.
| `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 {#custom-roles}
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 {#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",
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.
| `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.
```json
{
"name":"image-only",
"permissions":["tools:use","files:own"],
"toolPermissions":{
"mode":"category",
"allowed":["image"]
}
}
```
### Excluindo um papel personalizado {#deleting-a-custom-role}
Quando um papel personalizado é excluído, todos os usuários atribuídos a ele são automaticamente reatribuídos ao papel `user`.
## Times {#teams}
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 {#api-keys}
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 {#scoped-permissions}
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.
```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"
}'
```
### Expiração {#expiration}
As chaves aceitam um timestamp `expiresAt` opcional. Chaves expiradas são rejeitadas no momento da autenticação.
## Log de auditoria {#audit-log}
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 {#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
```
Requer a permissão `audit:read`. Suporta paginação (`page`, `limit`) e filtros (`action`, `ip`, `from`, `to`).
### Auditoria de operação de ferramentas {#tool-operation-auditing}
::: 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 {#exporting}
```
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 {#tamper-resistant-signing}
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 {#retention}
Defina `AUDIT_RETENTION_DAYS` para eliminar automaticamente entradas antigas. O padrão é `0`, o que significa que as entradas são mantidas indefinidamente.
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 {#role-changes-invalidate-sessions}
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 {#safety-guards}
- **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.
