المصادقة ومفاتيح API

متاح فيProResearch

يحمل كل استدعاء لـ REST API مفتاح API. المفتاح يتبع حسابك، وله النطاقات التي منحتها له، ويُحتسب ضمن حدود خطتك. توضح هذه الصفحة كيف تنشئ مفتاحًا وتستخدمه. قائمة النطاقات والحدود لكل خطة في المفاتيح والنطاقات والحدود.

قبل أن تبدأ

خطة Pro أو Research. حسابات Free تستطيع إنشاء مفاتيح MCP فقط، وهي تعمل مع خادم MCP وليس مع REST API. راجع ربط عميل MCP.

إنشاء مفتاح

افتح الإعدادات واختر الواجهة البرمجية وMCP.
تحت مفاتيح الواجهة البرمجية، اضغط إنشاء مفتاح.
اكتب اسم المفتاح يدل على المكان الذي يُستخدم فيه المفتاح، مثل nightly-sync.
حدّد الصلاحيات التي يحتاجها المفتاح ولا تزد عليها. نطاقات الكتابة تتيح للمفتاح تغيير مكتبتك، فلا تمنحها إلا لسكربتات تثق بها.
اضغط إنشاء.
انسخ المفتاح الآن. يبدأ بـ pk_، ويعرضه Readsira مرة واحدة فقط. بعد ذلك تعرض القائمة صيغة مختصرة مثل pk_1a2b...9z8y.

تعرض قائمة المفاتيح وقت آخر استخدام لكل مفتاح. المفتاح الذي لم يُستخدم قط يظهر عليه لم يُستخدم قط. عند أول استخدام للمفتاح يضيف Readsira إشعارًا في التطبيق يذكر اسم المفتاح، فيظهر أي استخدام غير متوقع.

إرسال المفتاح مع الطلب

أرسل المفتاح في ترويسة Authorization كرمز حامل (bearer token):

curl https://api.readsira.com/rest/v2/usage \
  -H "Authorization: Bearer $READSIRA_KEY"

وترويسة X-API-Key تعمل أيضًا:

curl https://api.readsira.com/rest/v2/usage \
  -H "X-API-Key: $READSIRA_KEY"

المفتاح داخل العنوان (?api_key=pk_...) يُرفض مع 401 والرمز API_KEY_IN_QUERY، لأن العناوين تنتهي في السجلات وتاريخ المتصفح.

احفظ المفتاح في متغير بيئة أو مخزن أسرار. لا تضعه في كود يُرفع إلى المستودع، ولا في صفحة ويب، ولا في تطبيق توزعه على الآخرين.

التحقق من أنه يعمل

يجيب GET /rest/v2/usage مع أي نطاق. يعرض خطتك وعدد طلبات اليوم وحدود هذا المفتاح.

{
  "success": true,
  "data": {
    "plan": "pro",
    "requestsToday": 12,
    "requestsPerDay": 10000,
    "mcpCallsToday": 0,
    "mcpCallsPerDay": 10000,
    "requestsPerHour": 600,
    "askAnswersPerMonth": 300,
    "aiBudget": [{ "group": "chat", "percentUsed": 3 }]
  },
  "meta": {
    "timestamp": "2026-11-04T09:00:00.000Z",
    "path": "/rest/v2/usage",
    "method": "GET",
    "statusCode": 200
  }
}

الأرقام أعلاه مثال؛ أرقامك هي حدود خطتك. إذا أعاد الاستدعاء 401 فالمفتاح خاطئ أو ملغى أو منتهي الصلاحية. وإذا أعاد 402 PLAN_REQUIRED فالحساب على خطة Free. راجع حدود المعدل والأخطاء.

أي نطاق يحتاجه المسار

يرفض المسار المفتاح الذي ينقصه نطاقه مع 403 SCOPE_REQUIRED. يذكر المرجع النطاق تحت كل مسار. أكثرها استخدامًا:

النطاق	يتيح للمفتاح
`read:library`	البحث وقراءة المستندات والمقاطع والنصوص المفرغة
`ask:library`	طرح أسئلة تأتي إجاباتها مع استشهادات (يستهلك ميزانية الذكاء الاصطناعي)
`read:projects`	عرض المشاريع وقراءة سياقها
`write:projects`	إضافة مصادر وملاحظات إلى المشاريع
`write:uploads`	رفع ملفات الصوت والفيديو وPDF
`read:bookmarks`, `write:bookmarks`	قراءة الإشارات المرجعية وكتابتها على مسارات `/api/v1/bookmarks`
`read:collections`	قراءة المجموعات على مسارات `/api/v1/collections`

إنشاء مفتاح بنطاق لا تشمله خطتك يعيد 400 SCOPE_NOT_ALLOWED.

استبدال مفتاح أو إزالته

في صف المفتاح، افتح قائمة الإجراءات.

إعادة الإنشاء يمنح المفتاح سرًّا جديدًا. يحتفظ المفتاح باسمه ونطاقاته وسجله، ويتوقف السر القديم عن العمل فورًا. استخدمه عند احتمال تسرّب المفتاح، ثم حدّث سكربتاتك.
إلغاء يحذف المفتاح. السكربتات التي تستخدمه تتوقف عن العمل.

تعرض قائمة النشاط في الصفحة نفسها كل استدعاء أجراه المفتاح: الوقت والمسار والحالة وعدد النتائج. ولا تخزّن نص بحثك أو محتوى مستنداتك.

نصائح

استخدم مفتاحًا واحدًا لكل سكربت، لتتمكن من إلغاء أحدها دون تعطيل البقية.
امنح المهام القرائية نطاقات القراءة فقط.
تعامل مع النص العائد من الصفحات المحفوظة كبيانات، وليس كتعليمات لنموذج.

قبل أن تبدأ​

إنشاء مفتاح​

إرسال المفتاح مع الطلب​

التحقق من أنه يعمل​

أي نطاق يحتاجه المسار​

استبدال مفتاح أو إزالته​

نصائح​

ذات صلة​