المصادقة

نظرة عامة

تتطلب جميع نقاط النهاية /v1/* مصادقة عبر ترويسة Authorization باستخدام رمز Bearer:

Authorization: Bearer <token>

مفاتيح API

مفاتيح API هي طريقة المصادقة الموصى بها للاستخدام من جانب الخادم والاستخدام البرمجي. فهي طويلة العمر وسهلة الإدارة ولا تتطلب أي حزم SDK خارجية.

إنشاء مفتاح API

يمكنك إنشاء مفاتيح API بطريقتين:

عبر لوحة التحكم:

1. انتقل إلى لوحة التحكم > الإعدادات > مفاتيح API.
2. انقر على إنشاء مفتاح API.
3. أدخل اسماً وصفياً واختر فترة انتهاء الصلاحية.
4. انسخ المفتاح فوراً.

عبر API:

curl -X POST https://api.docmap.io/v1/api-keys \
  -H "Authorization: Bearer <existing-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server",
    "expiresIn": "90d"
  }'

تنسيق المفتاح

تتبع مفاتيح API التنسيق التالي:

dm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

طول المفاتيح 72 حرفاً وتبدأ دائماً بالبادئة dm_live_.

خيارات انتهاء الصلاحية

عند إنشاء مفتاح، يمكنك الاختيار من فترات انتهاء الصلاحية التالية:

• 30 يوماً
• 60 يوماً
• 90 يوماً
• سنة واحدة
• بلا انتهاء (بدون انتهاء صلاحية)

WARNING

المفاتيح التي لا تنتهي صلاحيتها مريحة لكنها تحمل مخاطر أعلى في حالة الاختراق. استخدم أقصر فترة انتهاء صلاحية تلبي احتياجاتك.

الحدود

يمكن لكل حساب أن يمتلك حداً أقصى 10 مفاتيح API نشطة في أي وقت. قم بإلغاء المفاتيح غير المستخدمة لتحرير الفتحات.

مثال على الطلب

cURL

curl https://api.docmap.io/v1/extractions \
  -H "Authorization: Bearer dm_live_your_api_key"

TypeScript

const response = await fetch('https://api.docmap.io/v1/extractions', {
  headers: {
    'Authorization': `Bearer ${process.env.DOCMAP_API_KEY}`,
  },
})

استجابات الخطأ

إذا فشلت المصادقة، تُرجع واجهة API استجابة 401 Unauthorized:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired authentication token."
  }
}

الأسباب الشائعة:

• ترويسة Authorization مفقودة
• رمز مشوّه (بادئة أو تنسيق خاطئ)
• مفتاح API منتهي الصلاحية
• مفتاح API ملغى

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

DANGER

لا تكشف أبداً مفاتيح API في الكود من جانب العميل أو المستودعات العامة أو بيئات المتصفح. تمنح مفاتيح API وصولاً كاملاً إلى API حسابك ويجب التعامل معها كأسرار.

اتبع هذه الإرشادات للحفاظ على أمان بيانات اعتماد API الخاصة بك:

1. خزّن المفاتيح في متغيرات البيئة -- لا تكتب مفاتيح API مباشرة في الكود المصدري. استخدم متغيرات البيئة أو مدير الأسرار.

   # .env file (never commit this)
   DOCMAP_API_KEY=dm_live_your_api_key

   // Read from environment
   const apiKey = process.env.DOCMAP_API_KEY

2. قم بتدوير المفاتيح بشكل دوري -- أنشئ مفاتيح جديدة واستبدل القديمة وفق جدول منتظم، حتى لو لم يكن لديك سبب للشك بالاختراق.

3. ألغِ المفاتيح المخترقة فوراً -- إذا تم كشف مفتاح عن طريق الخطأ (مثلاً تم رفعه إلى مستودع عام)، ألغِه في لوحة التحكم > الإعدادات > مفاتيح API فوراً وأنشئ بديلاً.

4. استخدم أقصر فترة انتهاء صلاحية معقولة -- اختر فترة انتهاء صلاحية توازن بين الراحة والأمان. لمعظم حالات الاستخدام في الإنتاج، 90 يوماً هي القيمة الافتراضية الجيدة.

5. استخدم مفاتيح منفصلة لبيئات مختلفة -- أنشئ مفاتيح مميزة للتطوير والتجربة والإنتاج. هذا يحد من نطاق الضرر إذا تم اختراق مفتاح واحد ويسهّل تدوير المفاتيح دون توقف.

6. أضف ملف .env إلى .gitignore -- تأكد من عدم رفع ملفات البيئة إلى نظام التحكم بالإصدارات.

   # .gitignore
   .env
   .env.local
   .env.*.local