# Autenticação e Mind Keys

O Synapse usa dois métodos de autenticação, cada um otimizado para um caso de
uso diferente. Entender a diferença é essencial para construir integrações
confiáveis.

## Dois métodos de auth

| Método | Caso de uso | Limite de taxa | Expiração |
|--------|-------------|----------------|-----------|
| **Mind Key** | Agentes LLM, ferramentas automatizadas | Nenhum (header) / 60 min (query) | Nunca |
| **JWT** | Interface humana, operações de conta | Nenhum | 7 dias |

## Mind Key (para agentes)

Uma Mind Key é um token de API com escopo de tenant. Ele autentica os dados de
um único mind (memórias, tarefas, chat, scripts, etc.). Use para:

- Agentes LLM chamando a API
- Scripts de automação em background
- Configuração do servidor MCP
- Qualquer integração de longa duração

### Autenticação por cabeçalho (recomendada)

```bash
curl -H "Authorization: Bearer mk_yourMindKeyHere" \
     https://synapse.schaefer.zone/memory/recall
```

### Parâmetro de consulta (para ferramentas somente-URL)

```bash
curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere
```

> [!WARNING]
> O parâmetro de consulta `?key=` é limitado a **60 requisições por minuto**.
> O cabeçalho Bearer não tem limite de taxa. Use o cabeçalho sempre que seu
> cliente suportar cabeçalhos personalizados.

### Criando uma Mind Key

```bash
curl -X POST https://synapse.schaefer.zone/minds \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "Work Mind", "description": "Project memories"}'
```

A resposta inclui `mind_key` — **salve-a imediatamente**, ela é exibida apenas
uma vez.

### Listando seus minds

```bash
curl -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/minds
```

### Excluindo um mind (irreversível!)

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/minds/m_xyz789
```

## JWT (para humanos)

JWTs autenticam a **conta do usuário**, não um mind específico. Use-os para:

- Registro e login de conta
- Criar / listar / excluir minds
- Compartilhar minds com outros usuários
- Gerenciamento de assinaturas Web Push

### Registrar

```bash
curl -X POST https://synapse.schaefer.zone/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "secret"}'
```

Retorna: `{ "jwt": "eyJ...", "user": {...} }`

### Login

```bash
curl -X POST https://synapse.schaefer.zone/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "secret"}'
```

Retorna: `{ "jwt": "eyJ...", "user": {...} }`

### Expiração do JWT

JWTs expiram após **7 dias**. Quando um JWT expira, basta chamar `/login`
novamente para obter um novo. A Mind Key nunca expira, então integrações de
agentes existentes continuam funcionando.

## Melhores práticas de segurança

> [!CRITICAL]
> - **Nunca faça commit de Mind Keys no git.** Use variáveis de ambiente.
> - **Nunca registre Mind Keys em logs.** Mascarie-as em logs (`mk_***...***xyz`).
> - **Faça rotação de keys** se suspeitar de vazamento (exclua o mind, crie um novo).
> - **Use um mind por projeto** para limitar o raio de explosão se uma key vazar.

### Padrão de variável de ambiente

```bash
# .env (NEVER commit this file)
SYNAPSE_MIND_KEY=mk_yourMindKeyHere
SYNAPSE_URL=https://synapse.schaefer.zone
```

```typescript
// Node.js
const mindKey = process.env.SYNAPSE_MIND_KEY;
const url = process.env.SYNAPSE_URL;
await fetch(`${url}/memory/recall`, {
  headers: { Authorization: `Bearer ${mindKey}` },
});
```

### Configuração do servidor MCP

```json
{
  "mcpServers": {
    "synapse": {
      "command": "npx",
      "args": ["-y", "synapse-mcp-api@latest"],
      "env": {
        "SYNAPSE_MIND_KEY": "mk_yourMindKeyHere",
        "SYNAPSE_URL": "https://synapse.schaefer.zone"
      }
    }
  }
}
```

## Padrão multi-mind

Cada usuário pode ter múltiplos minds. Padrões comuns:

| Nome do mind | Finalidade |
|--------------|------------|
| `work` | Memórias relacionadas ao trabalho |
| `personal` | Preferências pessoais, família |
| `project-synapse` | Contexto de projeto específico |
| `learning-german` | Progresso de aprendizado |
| `assistant-default` | Fallback de propósito geral |

Use Mind Keys diferentes para sessões LLM diferentes para manter contextos
isolados.

## Limites de taxa

| Método de auth | Limite | Escopo |
|----------------|--------|--------|
| Mind Key (header) | Nenhum | Por mind |
| Mind Key (?key=) | 60/min | Por IP |
| JWT (header) | Nenhum | Por usuário |
| Endpoints públicos | Nenhum | Global |

Cabeçalhos de limite de taxa (`X-RateLimit-Limit`, `X-RateLimit-Remaining`,
`Retry-After`) são incluídos nas respostas quando aplicável.

## Próximos passos

- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — quando usar qual
- [API de Memória](/docs/api/memory) — o que você pode fazer com uma Mind Key
- [API de Usuário](/docs/api/user) — gerenciamento de conta com JWTs