---
title: "Autenticação"
description: "Os modos password e none, sessões no servidor, convites e redefinições, e a recuperação de admin pela CLI."
---

# Autenticação

A autenticação no Notarium é embutida e roda inteiramente sobre o banco de metadados — sem IdP externo, sem JWT, sem SMTP. O modo é escolhido pela variável `AUTH_MODE` e determina se existe login ou não.

## O modo `password` (padrão)

Seguro por padrão: autenticação multiusuário completa.

- **Primeira execução.** Numa instância limpa, o primeiro visitante cria o dono pela tela de configuração inicial (host-admin e dono dos espaços configurados). Não há senha pré-definida; uma vez registrada essa conta, a configuração se fecha de vez.
- **Sessões.** Um login cria uma **sessão no servidor** — uma linha no banco, não um JWT. Ela vive no cookie HttpOnly `nt_session`, com TTL deslizante de 30 dias e a flag `Secure` quando servido sob HTTPS. A revogação é imediata: desativar um usuário ou trocar uma senha derruba as sessões ativas na hora.
- **Um banco de metadados é obrigatório.** Ele já vem por padrão — SQLite sob `DATA_DIR`, nada a configurar. Você só mexe em `META_DB_URL` para migrar para um Postgres externo. Veja [Banco de dados](/docs/self-hosting/database/).

## O modo `none`

Um único principal com acesso total — o operador liga esse modo de forma deliberada, para o desktop, o desenvolvimento local ou uma intranet confiável. As rotas de autenticação retornam `404`, não há interface de login e nenhum banco de metadados é necessário para a autenticação.

> [!danger] Não exponha uma instância `none` à rede
> No modo `none`, qualquer um que alcance a porta ganha acesso total a todos os dados — inclusive ao endpoint MCP dos agentes. Use-o apenas em uma rede isolada ou confiável.

## Papéis e acesso

O acesso aos dados é concedido pela participação no espaço, e há três papéis:

| Papel | Permissões |
|---|---|
| `reader` | Lê tudo no espaço. |
| `writer` | Edita notas. |
| `owner` | Gerencia a participação. |

A flag **host-admin** dá controle sobre usuários e espaços, mas para **ler os dados** de um espaço específico você ainda precisa de participação nele. Mais sobre o modelo — [Modelo de acesso](/docs/concepts/access-model/).

## Convites e redefinições de senha

Não há SMTP no Notarium — a entrega inicial de uma conta é um **link de uso único** que o administrador repassa à mão. Um mecanismo, dois propósitos:

- **Convite** — adiciona um usuário sem senha; o link vive por 7 dias.
- **Redefinição de senha** — o link vive por 24 horas; aceitá-lo encerra as sessões antigas.

O token viaja no fragmento da URL (`/invite#<token>`), então nunca cai nos logs de acesso. Um usuário tem apenas um link desses ativo por vez, e o administrador nunca fica sabendo a senha de ninguém.

## Tokens para agentes

Agentes de IA se autenticam com um token de acesso pessoal (PAT) no formato `Authorization: Bearer ntp_…`, com escopo `read` ou `write`, opcionalmente restrito a espaços específicos. O segredo é exibido **exatamente uma vez**. A emissão de tokens e outras ações de gestão só ficam disponíveis dentro de uma sessão — um PAT vazado não consegue escalar privilégios. Detalhes — [Conectar um agente](/docs/agents/connect/) e [Segurança e visibilidade](/docs/agents/security/).

## Recuperando o acesso

Como só o administrador emite um link de redefinição, perder a senha do único admin significaria perder o acesso. A solução é a **CLI de administração**, que atua diretamente sobre o banco de metadados. Ela é um dos comandos embutidos da imagem, por isso a chamada é curta e vai direto para o contêiner em execução:

```bash
docker compose exec notarium admin create-admin <user> --random

# para um docker run puro:
docker exec -it notarium admin create-admin <user> --random
```

Não é preciso parar o servidor: o SQLite em modo WAL tolera um segundo escritor, e o Postgres, com ainda mais folga. A própria CLI encontra o banco de metadados, seguindo a mesma lógica do servidor (`META_DB_URL`, ou a raiz derivada de `DATA_DIR`); diante de um caminho errado, ela sai com erro em vez de criar silenciosamente um banco vazio onde "não há usuários".

Comandos disponíveis:

| Comando | Ação |
|---|---|
| `list` | Lista os usuários. |
| `passwd <user> [--password <pw> \| --random]` | Troca uma senha. |
| `create-admin <user> [--random] [--display "Name"]` | Cria um administrador. |
| `grant <user> <space> <owner\|writer\|reader>` | Concede um papel em um espaço. |

Sem flag, a senha é lida do stdin com o eco suprimido, então nunca cai no histórico de comandos. `setPassword`/`createAdmin` só estão disponíveis **pela CLI** — não há caminho HTTP para elas: este é o limite de operador do host. Os demais comandos da imagem estão na página [CLI da imagem](/docs/self-hosting/cli/).