{"title":"المصادقة و Mind Keys","slug":"authentication","category":"getting-started","summary":"كيف تعمل مصادقة Synapse: Mind Keys للوكلاء، JWTs للبشر، ?key= للأدوات التي تفتح عناوين URL فقط.","audience":["human","llm"],"tags":["auth","mind-key","jwt","security"],"difficulty":"beginner","updated":"2026-06-27","word_count":457,"read_minutes":2,"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":"ar","translated":true,"requested_lang":"ar","content_markdown":"\n# المصادقة و Mind Keys\n\nيستخدم Synapse طريقتين للمصادقة، كلٌّ مُحسّنة لحالة استخدام مختلفة.\nفهم الفرق أساسي لبناء تكاملات موثوقة.\n\n## طريقتان للمصادقة\n\n| الطريقة | حالة الاستخدام | حد المعدل | الانتهاء |\n|--------|----------|------------|--------|\n| **Mind Key** | وكلاء LLM، الأدوات المؤتمتة | لا شيء (ترويسة) / 60 دقيقة (استعلام) | أبدًا |\n| **JWT** | واجهة الإنسان، عمليات الحساب | لا شيء | 7 أيام |\n\n## Mind Key (للوكلاء)\n\nMind Key رمز API محدود بمستأجر. يُصادق بيانات عقل واحد\n(الذكريات، المهام، الدردشة، السكربتات، إلخ). استخدمه لـ:\n\n- وكلاء LLM الذين يستدعون الـ API\n- سكربتات الأتمتة الخلفية\n- إعداد خادم MCP\n- أي تكامل طويل الأمد\n\n### مصادقة الترويسة (موصى بها)\n\n```bash\ncurl -H \"Authorization: Bearer mk_yourMindKeyHere\" \\\n https://synapse.schaefer.zone/memory/recall\n```\n\n### معامل الاستعلام (للأدوات التي تفتح عناوين URL فقط)\n\n```bash\ncurl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere\n```\n\n> [!WARNING]\n> معامل الاستعلام `?key=` محدود بـ **60 طلبًا في الدقيقة**.\n> ترويسة Bearer بلا حد معدل. استخدم الترويسة كلما دعم عميلك\n> الترويسات المخصصة.\n\n### إنشاء 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\nتتضمن الاستجابة `mind_key` — **احفظه فورًا**، يُعرض مرة واحدة فقط.\n\n### سرد عقلك\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds\n```\n\n### حذف عقل (لا يمكن التراجع!)\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds/m_xyz789\n```\n\n## JWT (للبشر)\n\nتُصادق JWTs **حساب المستخدم**، لا عقلًا محددًا. استخدمها لـ:\n\n- تسجيل الحساب والدخول\n- إنشاء / سرد / حذف العقول\n- مشاركة العقول مع مستخدمين آخرين\n- إدارة اشتراك Web Push\n\n### تسجيل\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\nيُرجع: `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### تسجيل الدخول\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\nيُرجع: `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### انتهاء JWT\n\nتنتهي JWTs بعد **7 أيام**. عند انتهاء JWT، استدعِ `/login` مرة أخرى للحصول\nعلى واحد جديد. لا تنتهي Mind Key أبدًا، لذا تستمر تكاملات الوكلاء\nبالعمل.\n\n## أفضل ممارسات الأمان\n\n> [!CRITICAL]\n> - **لا تلتزم Mind Keys في git أبدًا.** استخدم متغيرات البيئة.\n> - **لا تسجّل Mind Keys أبدًا.** قنّعها في السجلات (`mk_***...***xyz`).\n> - **دوّر المفاتيح** إذا اشتبهت في تسريب (احذف العقل، أنشئ واحدًا جديدًا).\n> - **استخدم عقلًا واحدًا لكل مشروع** لتحديد دائرة الضرر إذا تسرب مفتاح.\n\n### نمط متغير البيئة\n\n```bash\n# .env (لا تلتزم هذا الملف أبدًا)\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### إعداد خادم 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## نمط العقول المتعددة\n\nيستطيع كل مستخدم امتلاك عقول متعددة. أنماط شائعة:\n\n| اسم العقل | الغرض |\n|-----------|---------|\n| `work` | ذكريات العمل |\n| `personal` | التفضيلات الشخصية، العائلة |\n| `project-synapse` | سياق مشروع محدد |\n| `learning-german` | تقدّم التعلم |\n| `assistant-default` | بديل للأغراض العامة |\n\nاستخدم Mind Keys مختلفة لجلسات LLM مختلفة للحفاظ على عزل السياقات.\n\n## حدود المعدل\n\n| طريقة المصادقة | الحد | النطاق |\n|-------------|-------|-------|\n| Mind Key (ترويسة) | لا شيء | لكل عقل |\n| Mind Key (?key=) | 60/دقيقة | لكل IP |\n| JWT (ترويسة) | لا شيء | لكل مستخدم |\n| نقاط النهاية العامة | لا شيء | عام |\n\nتُتضمن ترويسات حد المعدل (`X-RateLimit-Limit`، `X-RateLimit-Remaining`، `Retry-After`)\nفي الاستجابات عند الاقتضاء.\n\n## الخطوات التالية\n\n- [Mind Key مقابل JWT](/docs/getting-started/mind-key-vs-jwt) — متى تستخدم أيًّا منهما\n- [Memory API](/docs/api/memory) — ما تستطيع فعله بـ Mind Key\n- [User API](/docs/api/user) — إدارة الحساب بـ JWTs\n","content_html":"

المصادقة و Mind Keys

\n

يستخدم Synapse طريقتين للمصادقة، كلٌّ مُحسّنة لحالة استخدام مختلفة.\nفهم الفرق أساسي لبناء تكاملات موثوقة.

\n

طريقتان للمصادقة

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
الطريقةحالة الاستخدامحد المعدلالانتهاء
Mind Keyوكلاء LLM، الأدوات المؤتمتةلا شيء (ترويسة) / 60 دقيقة (استعلام)أبدًا
JWTواجهة الإنسان، عمليات الحسابلا شيء7 أيام
\n

Mind Key (للوكلاء)

\n

Mind Key رمز API محدود بمستأجر. يُصادق بيانات عقل واحد\n(الذكريات، المهام، الدردشة، السكربتات، إلخ). استخدمه لـ:

\n\n

مصادقة الترويسة (موصى بها)

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

معامل الاستعلام (للأدوات التي تفتح عناوين URL فقط)

\n
curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere
معامل الاستعلام `?key=` محدود بـ **60 طلبًا في الدقيقة**.\nترويسة Bearer بلا حد معدل. استخدم الترويسة كلما دعم عميلك\nالترويسات المخصصة.

إنشاء 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"}'

تتضمن الاستجابة mind_key — احفظه فورًا، يُعرض مرة واحدة فقط.

\n

سرد عقلك

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

حذف عقل (لا يمكن التراجع!)

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

JWT (للبشر)

\n

تُصادق JWTs حساب المستخدم، لا عقلًا محددًا. استخدمها لـ:

\n\n

تسجيل

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

يُرجع: { "jwt": "eyJ...", "user": {...} }

\n

تسجيل الدخول

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

يُرجع: { "jwt": "eyJ...", "user": {...} }

\n

انتهاء JWT

\n

تنتهي JWTs بعد 7 أيام. عند انتهاء JWT، استدعِ /login مرة أخرى للحصول\nعلى واحد جديد. لا تنتهي Mind Key أبدًا، لذا تستمر تكاملات الوكلاء\nبالعمل.

\n

أفضل ممارسات الأمان

\n

نمط متغير البيئة

\n
# .env (لا تلتزم هذا الملف أبدًا)\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});

إعداد خادم 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}

نمط العقول المتعددة

\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
اسم العقلالغرض
workذكريات العمل
personalالتفضيلات الشخصية، العائلة
project-synapseسياق مشروع محدد
learning-germanتقدّم التعلم
assistant-defaultبديل للأغراض العامة
\n

استخدم Mind Keys مختلفة لجلسات LLM مختلفة للحفاظ على عزل السياقات.

\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\n
طريقة المصادقةالحدالنطاق
Mind Key (ترويسة)لا شيءلكل عقل
Mind Key (?key=)60/دقيقةلكل IP
JWT (ترويسة)لا شيءلكل مستخدم
نقاط النهاية العامةلا شيءعام
\n

تُتضمن ترويسات حد المعدل (X-RateLimit-Limit، X-RateLimit-Remaining، Retry-After)\nفي الاستجابات عند الاقتضاء.

\n

الخطوات التالية

\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"]}