المصادقة

أرسل مفتاحك في ترويسة Authorization مع كل طلب:

Authorization: Bearer dk_live_…

• المفاتيح سرية. استدعِ API من خوادمك فقط، لا من المتصفحات أو تطبيقات الجوال أو المستودعات العامة.
• يُرفض المفتاح المرسل في الرابط (?api_key=) بالرمز api_key_in_query. دوّر أي مفتاح سبق وضعه في رابط.
• يمكن للحساب الاحتفاظ بعدة مفاتيح ضمن مشاريع. يمكن تقييد المفتاح ببعض واجهات API وتحديد تاريخ انتهاء له؛ تفشل الطلبات خارج صلاحياته بالرمز scope_not_in_key، ويحصل المفتاح المنتهي على expired_api_key.
• لتدوير مفتاح، استخدم تدوير في لوحة التحكم: تحصل على مفتاح جديد بالإعدادات نفسها، ويستمر القديم خلال مهلة السماح التي تختارها حتى تنشر التحديث دون توقف. يسري الإلغاء فورًا.

حفظ المفتاح. احفظه في متغير بيئة أو مدير أسرار، لا في نظام التحكم بالمصدر. تبدأ المفاتيح بالبادئة الثابتة dk_live_ أو dk_admin_ لتسهيل اكتشافها بأدوات فحص الأسرار. إذا وصل مفتاح إلى مستودع عام، دوّره فورًا وألغِ القديم بعد اكتمال النشر.

نوعان من المفاتيح. يقرأ مفتاح البيانات (dk_live_…) الإعلانات وبيانات السوق والتحليلات والمشاريع العقارية. ينشئ مالك المؤسسة مفتاح الإدارة (dk_admin_…) لإدارة المؤسسة نفسها: المفاتيح والمشاريع والأعضاء والاستخدام وأحداث التدقيق. وهو النوع الوحيد المقبول في نقاط نهاية /v1/organization. لا تتداخل صلاحيات النوعين: يحصل مفتاح البيانات في نقطة إدارة على admin_key_required، ومفتاح الإدارة في غيرها على admin_key_not_allowed. لا تُحتسب وحدات لطلبات الإدارة.

مفاتيح الاختبار. يقرأ مفتاح dk_test_… البيانات الحية نفسها، بحصة ثابتة قدرها 1,000 وحدة شهريًا و30 وحدة في الدقيقة و25 نتيجة في الصفحة وعمق 250 نتيجة. يُقاس استخدامه منفصلًا، فلا يستهلك مفتاح اختبار يعمل في CI حصة تكامل الإنتاج، ولا تنشأ عنه فاتورة؛ الاستخدام الإضافي معطّل مهما سمحت الخطة. يصل إلى واجهات API نفسها التي تشملها خطتك، فتختبر ما ستستخدمه في الإنتاج. أنشئه من صفحة مفاتيح API؛ يمكن للمؤسسة الاحتفاظ بثلاثة مفاتيح اختبار، منفصلة عن حد المفاتيح الحية.

OAuth لخادم MCP، لا للطلبات المباشرة. يربط المستخدمون مساعدي الذكاء الاصطناعي عبر Darak MCP بتسجيل الدخول باستخدام OAuth. يستبدل خادم MCP رمزهم ببيانات اعتماد API قصيرة الأجل مرتبطة بالمؤسسة المختارة عند الموافقة، فتُحتسب الطلبات على خطتها وتظهر في سجلاتها. لا يقبل API رموز عملاء MCP مباشرة؛ استخدم مفتاحًا للخادم أو النص البرمجي أو المهمة المجدولة.