Xác thực & Mind Key

Synapse sử dụng hai phương thức xác thực, mỗi phương thức được tối ưu cho một trường hợp sử dụng khác nhau. Hiểu sự khác biệt là điều thiết yếu để xây dựng tích hợp đáng tin cậy.

Hai phương thức xác thực

Mind Key (cho Agent)

Mind Key là token API phạm vi tenant. Nó xác thực dữ liệu của một mind duy nhất (bộ nhớ, tác vụ, chat, script, v.v.). Sử dụng nó cho:

• LLM agent gọi API
• Script tự động hóa nền
• Cấu hình MCP server
• Bất kỳ tích hợp tồn tại lâu dài nào

Xác thực header (khuyến nghị)

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

Tham số query (cho công cụ chỉ dùng URL)

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

Tạo 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"}'

Phản hồi bao gồm mind_key — lưu ngay lập tức, nó chỉ hiển thị một lần.

Liệt kê mind của bạn

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

Xóa mind (không thể đảo ngược!)

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

JWT (cho Con người)

JWT xác thực tài khoản người dùng, không phải một mind cụ thể. Sử dụng cho:

• Đăng ký và đăng nhập tài khoản
• Tạo / liệt kê / xóa mind
• Chia sẻ mind với người dùng khác
• Quản lý đăng ký Web Push

Đăng ký

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

Trả về: { "jwt": "eyJ...", "user": {...} }

Đăng nhập

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

Trả về: { "jwt": "eyJ...", "user": {...} }

Hết hạn JWT

JWT hết hạn sau 7 ngày. Khi JWT hết hạn, chỉ cần gọi lại /login để lấy JWT mới. Mind Key không bao giờ hết hạn, do đó các tích hợp agent hiện tại tiếp tục hoạt động.

Thực hành bảo mật tốt nhất

Mẫu biến môi trường

# .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}` },
});

Cấu hình MCP server

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

Mẫu Multi-Mind

Mỗi người dùng có thể có nhiều mind. Mẫu phổ biến:

Sử dụng các Mind Key khác nhau cho các phiên LLM khác nhau để giữ ngữ cảnh tách biệt.

Giới hạn tốc độ

Header giới hạn tốc độ (X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After) được bao gồm trong phản hồi khi áp dụng.

Bước tiếp theo

• Mind Key vs JWT — khi nào dùng cái nào
• Memory API — những gì bạn có thể làm với Mind Key
• User API — quản lý tài khoản với JWT