مفاتيح الوصول
تكشف مشاريع HeroMate مجموعة صغيرة من المفاتيح والرموز لسياقات مختلفة. أهم قاعدة بسيطة:
- استخدم
jwtلتدفقات التطبيق الموجّهة للمستخدم - استخدم
API Keyالمشروع فقط للاستدعاءات من خادم إلى خادم - عامل
service_roleكداخلي/إدارة فقط
عامل كل المفاتيح ككلمات مرور. لا تعرض أبداً مفاتيح API المشروع أو بيانات اعتماد service-role في كود المتصفح أو المستودعات العامة أو متغيّرات NEXT_PUBLIC_*.
بيانات الاعتماد الثلاث للوصول
API Key
استخدم API Key المشروع لـ endpoints المضبوطة بـ auth_mode: "api_key".
- يُرسل عبر رأس
X-API-KEY - يُقبل فقط على endpoints المضبوطة صراحة بـ
auth_mode: "api_key" - مخصّص لبيئات جانب الخادم فقط
- الأفضل لمهام الخلفية والعمال ومهام cron و Route Handlers والتكاملات من خادم إلى خادم
- ليس للمتصفح أو عملاء الجوال
- يوجد تحت Settings → API Keys (المسار
/api/keys)
يصادق API Key المشروع على الاستدعاءات إلى endpoints في HeroMate. ليس نفسه مفتاح مزوّد طرف ثالث (Stripe أو OpenAI أو Telegram…). تلك تذهب في بيانات الاعتماد، حيث تُخزَّن مكتوبة الأنواع ومشفّرة.
Service Role Key
هذا بيانات اعتماد داخلية بامتياز عالٍ.
- يُرسل عبر
Authorization: Bearer <key> - يمنح وصول
service_roleداخلياً - محجوز لبنية الخلفية الموثوقة أو دواخل الإدارة أو الهجرات أو الأدوات الخاصة
- ليس جزءاً من تصميم التطبيق العادي
- لا تعرضه أبداً خارج سياق خادم آمن
رمز MCP
استخدم رمز MCP لربط عملاء الذكاء الاصطناعي مثل Claude Code و Codex و Cursor و Windsurf أو Antigravity (وأي أداة متوافقة مع MCP) بمشروعك.
- يُستخدم في إعداد MCP
- يتيح لمساعد الذكاء الاصطناعي فحص موارد المشروع والعمل عليها
- يُنشأ في صفحة المؤسسة "Conectar IA" (رموز MCP) على
/{org}/mcp/tokens— بطاقة MCP في الشريط الجانبي للبوابة
أيها يجب أن أستخدم؟
| بيانات الاعتماد | أين تستخدمه | الرأس | حالة الاستخدام النموذجية |
|---|---|---|---|
| جلسة JWT | متصفح أو تطبيق جوال | Authorization: Bearer <user-token> | تدفقات المستخدم المسجّل |
| API Key | كود جانب الخادم فقط | X-API-KEY | Endpoints من خادم إلى خادم |
| Service Role Key | خلفية داخلية فقط | Authorization: Bearer <key> | عمليات إدارة/نظام داخلية |
| رمز MCP | إعداد MCP لعميل الذكاء الاصطناعي | إعداد MCP | ربط Claude Code أو Codex أو Cursor أو Windsurf أو Antigravity |
استخدام SDK
تطبيق موجّه للمستخدم
لمصادقة المتصفح أو التطبيق، هيّئ SDK بعنوان URL مشروعك فقط:
import { createClient } from '@dypai-ai/client-sdk'
const dypai = createClient(process.env.NEXT_PUBLIC_DYPAI_URL!)
هذا الإعداد العادي لـ:
- تسجيل الدخول
- التسجيل
- استعادة كلمة المرور
- استدعاء endpoints من نوع
jwtمن الواجهة
تطبيق جانب الخادم
إذا احتجت استدعاء endpoints من نوع api_key من كود الخلفية:
import { createClient } from '@dypai-ai/client-sdk'
const dypaiServer = createClient(
process.env.DYPAI_URL!,
process.env.DYPAI_API_KEY
)
خزّن المفاتيح في متغيّرات بيئة جانب الخادم فقط ولا تضمّنها أبداً في ملفات المصدر.
# .env
DYPAI_URL=https://your-project.dypai.app
DYPAI_API_KEY=your-project-api-key
DYPAI_SERVICE_KEY=your-internal-service-key
نمط الاستخدام الموصى به
لمعظم المشاريع:
- استخدم
jwtلـ endpoints والشاشات الموجّهة للمستخدم. - استخدم
api_keyفقط لأتمتة الخلفية أو التكاملات. - أبقِ
service_roleخارج هندسة التطبيق العادية.
إذا بدأت بأتمتة الخلفية قبل جاهزية مصادقة المستخدم، استخدام endpoints من نوع api_key أولاً جيد. عندما تصل التدفقات الموجّهة للمستخدم، أضف endpoints من نوع jwt لتلك إجراءات التطبيق.
أفضل ممارسات الأمان
- لا تعرض أبداً API Key المشروع في كود المتصفح
- لا تضع أبداً
DYPAI_API_KEYفيNEXT_PUBLIC_*أو متغيّرات بيئة عامة مشابهة - احجز Service Role Key لعمليات الخلفية الداخلية فقط
- دوّر المفاتيح إذا اشتبهت باختراق
- أضف
.envإلى.gitignore
الخطوات التالية
- المصادقة — افهم مصادقة المستخدم والأدوار وحماية endpoints
- Endpoints — ابنِ endpoints الـ API الخاصة بك واكشفها
- بيانات الاعتماد — خزّن مفاتيح مزوّدي الأطراف الثالثة (Stripe و OpenAI و Telegram…)
- مصادقة SDK — نفّذ تدفقات تسجيل الدخول والتسجيل والاستعادة