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

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)

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

Parâmetro de consulta (desabilitado por padrão)

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

Criando uma Mind Key

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

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

Excluindo um mind (irreversível!)

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

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

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

Padrão de variável de ambiente

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

// 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

{
  "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:

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

Limites de taxa

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 — quando usar qual
• API de Memória — o que você pode fazer com uma Mind Key
• API de Usuário — gerenciamento de conta com JWTs