Skip to main content

Xác thực & Mind Key

beginner 🤖 Thân thiện với LLM 4 phút · 733 từ Cập nhật: 2026-11-04 Tiếng Việt

Cách xác thực Synapse hoạt động: Mind Key cho agent, JWT cho con người, ?key= tắt theo mặc định (chỉ Bearer, AUTH_QUERY_KEY_MODE=deny).

Đọc bài viết này ở định dạng: 📄 Văn bản thuần ⚡ JSON 🤖 Định dạng LLM
Ngôn ngữ: English中文हिन्दीEspañolFrançaisالعربيةPortuguêsРусский日本語DeutschItaliano한국어NederlandsPolskiTürkçeSvenskaTiếng ViệtไทยBahasa IndonesiaУкраїнська

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

Phương thức Trường hợp Giới hạn tốc độ Hết hạn
Mind Key LLM agent, công cụ tự động 120/phút (Bearer ngoài); ?key= tắt theo mặc định (deny) Không bao giờ
JWT Giao diện hướng con người, thao tác tài khoản 120/phút (IP bên ngoài) 7 ngày

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 (tắt theo mặc định)

curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere
Tham số query `?key=` được **tắt** bởi mặc định đã siết `AUTH_QUERY_KEY_MODE=deny`: máy chủ trả về `?key=` với 401 kèm gợi ý "Query-param auth (?key=) is disabled". Chỉ Bearer là mặc định an toàn (SSOT: `src/lib/auth.ts`). Chỉ khi một nhà vận hành đặt rõ ràng `AUTH_QUERY_KEY_MODE=allow`, `?key=` mới hoạt động như van chuyển tiếp với 60 req/min (mỗi IP). Client Bearer bên ngoài nhận 120 req/min theo danh tính; mạng nội bộ đáng tin cậy không giới hạn. Sử dụng header bất cứ khi nào client của bạn hỗ trợ header tùy chỉnh.

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:

Tên Mind Mục đích
work Bộ nhớ liên quan công việc
personal Sở thích cá nhân, gia đình
project-synapse Ngữ cảnh dự án cụ thể
learning-german Tiến độ học tập
assistant-default Fallback mục đích chung

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 độ

Phương thức xác thực Giới hạn Phạm vi
Mind Key (header) 120/phút từ IP bên ngoài (mỗi định danh); không giới hạn cho mạng nội bộ đáng tin cậy Mỗi mind
Mind Key (?key=, chỉ khi allow) 60/phút Mỗi IP
JWT (header) 120 yêu cầu/phút (IP bên ngoài; không giới hạn cho mạng nội bộ đáng tin cậy) Mỗi người dùng
Endpoint công khai Không Toàn cầu

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

← Quay lại Bắt Đầu