{"title":"Autenticação e Mind Keys","slug":"authentication","category":"getting-started","summary":"Como funciona a autenticação do Synapse: Mind Keys para agentes, JWTs para humanos, ?key= para ferramentas somente-URL.","audience":["human","llm"],"tags":["auth","mind-key","jwt","security"],"difficulty":"beginner","updated":"2026-06-27","word_count":531,"read_minutes":3,"llm_context":"Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).\nMind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)\nJWT: Authorization: Bearer eyJ... (no rate limit, used for /register, /login, /minds, /sharing)\nMind Key is shown only once at creation. Store it permanently.\nEach mind has exactly one Mind Key. Multiple minds = multiple keys.\n","lang":"pt","translated":true,"requested_lang":"pt","content_markdown":"\n# Autenticação e Mind Keys\n\nO Synapse usa dois métodos de autenticação, cada um otimizado para um caso de\nuso diferente. Entender a diferença é essencial para construir integrações\nconfiáveis.\n\n## Dois métodos de auth\n\n| Método | Caso de uso | Limite de taxa | Expiração |\n|--------|-------------|----------------|-----------|\n| **Mind Key** | Agentes LLM, ferramentas automatizadas | Nenhum (header) / 60 min (query) | Nunca |\n| **JWT** | Interface humana, operações de conta | Nenhum | 7 dias |\n\n## Mind Key (para agentes)\n\nUma Mind Key é um token de API com escopo de tenant. Ele autentica os dados de\num único mind (memórias, tarefas, chat, scripts, etc.). Use para:\n\n- Agentes LLM chamando a API\n- Scripts de automação em background\n- Configuração do servidor MCP\n- Qualquer integração de longa duração\n\n### Autenticação por cabeçalho (recomendada)\n\n```bash\ncurl -H \"Authorization: Bearer mk_yourMindKeyHere\" \\\n https://synapse.schaefer.zone/memory/recall\n```\n\n### Parâmetro de consulta (para ferramentas somente-URL)\n\n```bash\ncurl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere\n```\n\n> [!WARNING]\n> O parâmetro de consulta `?key=` é limitado a **60 requisições por minuto**.\n> O cabeçalho Bearer não tem limite de taxa. Use o cabeçalho sempre que seu\n> cliente suportar cabeçalhos personalizados.\n\n### Criando uma Mind Key\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/minds \\\n -H \"Authorization: Bearer YOUR_JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"Work Mind\", \"description\": \"Project memories\"}'\n```\n\nA resposta inclui `mind_key` — **salve-a imediatamente**, ela é exibida apenas\numa vez.\n\n### Listando seus minds\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds\n```\n\n### Excluindo um mind (irreversível!)\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds/m_xyz789\n```\n\n## JWT (para humanos)\n\nJWTs autenticam a **conta do usuário**, não um mind específico. Use-os para:\n\n- Registro e login de conta\n- Criar / listar / excluir minds\n- Compartilhar minds com outros usuários\n- Gerenciamento de assinaturas Web Push\n\n### Registrar\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/register \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"you@example.com\", \"password\": \"secret\"}'\n```\n\nRetorna: `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### Login\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/login \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"you@example.com\", \"password\": \"secret\"}'\n```\n\nRetorna: `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### Expiração do JWT\n\nJWTs expiram após **7 dias**. Quando um JWT expira, basta chamar `/login`\nnovamente para obter um novo. A Mind Key nunca expira, então integrações de\nagentes existentes continuam funcionando.\n\n## Melhores práticas de segurança\n\n> [!CRITICAL]\n> - **Nunca faça commit de Mind Keys no git.** Use variáveis de ambiente.\n> - **Nunca registre Mind Keys em logs.** Mascarie-as em logs (`mk_***...***xyz`).\n> - **Faça rotação de keys** se suspeitar de vazamento (exclua o mind, crie um novo).\n> - **Use um mind por projeto** para limitar o raio de explosão se uma key vazar.\n\n### Padrão de variável de ambiente\n\n```bash\n# .env (NEVER commit this file)\nSYNAPSE_MIND_KEY=mk_yourMindKeyHere\nSYNAPSE_URL=https://synapse.schaefer.zone\n```\n\n```typescript\n// Node.js\nconst mindKey = process.env.SYNAPSE_MIND_KEY;\nconst url = process.env.SYNAPSE_URL;\nawait fetch(`${url}/memory/recall`, {\n headers: { Authorization: `Bearer ${mindKey}` },\n});\n```\n\n### Configuração do servidor MCP\n\n```json\n{\n \"mcpServers\": {\n \"synapse\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"synapse-mcp-api@latest\"],\n \"env\": {\n \"SYNAPSE_MIND_KEY\": \"mk_yourMindKeyHere\",\n \"SYNAPSE_URL\": \"https://synapse.schaefer.zone\"\n }\n }\n }\n}\n```\n\n## Padrão multi-mind\n\nCada usuário pode ter múltiplos minds. Padrões comuns:\n\n| Nome do mind | Finalidade |\n|--------------|------------|\n| `work` | Memórias relacionadas ao trabalho |\n| `personal` | Preferências pessoais, família |\n| `project-synapse` | Contexto de projeto específico |\n| `learning-german` | Progresso de aprendizado |\n| `assistant-default` | Fallback de propósito geral |\n\nUse Mind Keys diferentes para sessões LLM diferentes para manter contextos\nisolados.\n\n## Limites de taxa\n\n| Método de auth | Limite | Escopo |\n|----------------|--------|--------|\n| Mind Key (header) | Nenhum | Por mind |\n| Mind Key (?key=) | 60/min | Por IP |\n| JWT (header) | Nenhum | Por usuário |\n| Endpoints públicos | Nenhum | Global |\n\nCabeçalhos de limite de taxa (`X-RateLimit-Limit`, `X-RateLimit-Remaining`,\n`Retry-After`) são incluídos nas respostas quando aplicável.\n\n## Próximos passos\n\n- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — quando usar qual\n- [API de Memória](/docs/api/memory) — o que você pode fazer com uma Mind Key\n- [API de Usuário](/docs/api/user) — gerenciamento de conta com JWTs\n","content_html":"

Autenticação e Mind Keys

\n

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

\n

Dois métodos de auth

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
MétodoCaso de usoLimite de taxaExpiração
Mind KeyAgentes LLM, ferramentas automatizadasNenhum (header) / 60 min (query)Nunca
JWTInterface humana, operações de contaNenhum7 dias
\n

Mind Key (para agentes)

\n

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

\n\n

Autenticação por cabeçalho (recomendada)

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

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

\n
curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere
O parâmetro de consulta `?key=` é limitado a **60 requisições por minuto**.\nO cabeçalho Bearer não tem limite de taxa. Use o cabeçalho sempre que seu\ncliente suportar cabeçalhos personalizados.

Criando uma Mind Key

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

A resposta inclui mind_key — salve-a imediatamente, ela é exibida apenas\numa vez.

\n

Listando seus minds

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

Excluindo um mind (irreversível!)

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

JWT (para humanos)

\n

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

\n\n

Registrar

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

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

\n

Login

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

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

\n

Expiração do JWT

\n

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

\n

Melhores práticas de segurança

\n

Padrão de variável de ambiente

\n
# .env (NEVER commit this file)\nSYNAPSE_MIND_KEY=mk_yourMindKeyHere\nSYNAPSE_URL=https://synapse.schaefer.zone
// Node.js\nconst mindKey = process.env.SYNAPSE_MIND_KEY;\nconst url = process.env.SYNAPSE_URL;\nawait fetch(`${url}/memory/recall`, {\n  headers: { Authorization: `Bearer ${mindKey}` },\n});

Configuração do servidor MCP

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

Padrão multi-mind

\n

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Nome do mindFinalidade
workMemórias relacionadas ao trabalho
personalPreferências pessoais, família
project-synapseContexto de projeto específico
learning-germanProgresso de aprendizado
assistant-defaultFallback de propósito geral
\n

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

\n

Limites de taxa

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Método de authLimiteEscopo
Mind Key (header)NenhumPor mind
Mind Key (?key=)60/minPor IP
JWT (header)NenhumPor usuário
Endpoints públicosNenhumGlobal
\n

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

\n

Próximos passos

\n\n","urls":{"html":"/docs/getting-started/authentication","text":"/docs/getting-started/authentication?format=text","json":"/docs/getting-started/authentication?format=json","llm":"/docs/getting-started/authentication?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}