إدارة مفاتيح API

نظرة عامة

توفر مفاتيح API وصولاً برمجياً إلى DocMap API. كل مفتاح هو رمز من 72 حرفاً مسبوق بـ dm_live_ تمرره كرمز Bearer في ترويسة Authorization.

حقائق أساسية:

• حد أقصى 10 مفاتيح نشطة لكل حساب
• التنسيق: dm_live_ متبوعة بـ 64 حرفاً سداسي عشري عشوائي (72 حرفاً إجمالاً)
• تُجزّأ المفاتيح قبل التخزين -- يُعرض المفتاح الخام مرة واحدة فقط عند الإنشاء
• يمكن تحديد المفاتيح بتواريخ انتهاء صلاحية أو ضبطها لعدم الانتهاء أبداً

إنشاء مفتاح

من لوحة التحكم

1. انتقل إلى الإعدادات > مفاتيح API في لوحة تحكم DocMap الخاصة بك
2. انقر على إنشاء مفتاح API
3. أدخل اسماً وصفياً (مثال: "خادم الإنتاج" أو "خط أنابيب CI/CD")
4. اختر فترة انتهاء الصلاحية
5. انسخ المفتاح المعروض فوراً -- لن يُعرض مرة أخرى

من API

يمكنك أيضاً إنشاء مفاتيح برمجياً بالمصادقة بمفتاح API موجود:

curl

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

TypeScript

const response = await fetch("https://api.docmap.io/v1/api-keys", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${existingApiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Production Server",
    expiresIn: "90d",
  }),
});

const { data } = await response.json();

// Store this immediately -- it will never be shown again
console.log("API Key:", data.key);
console.log("Key ID:", data.apiKey.id);

Python

import requests

response = requests.post(
    "https://api.docmap.io/v1/api-keys",
    headers={
        "Authorization": f"Bearer {existing_api_key}",
        "Content-Type": "application/json",
    },
    json={
        "name": "Production Server",
        "expiresIn": "90d",
    },
)

data = response.json()["data"]

# Store this immediately -- it will never be shown again
print("API Key:", data["key"])
print("Key ID:", data["apiKey"]["id"])

قيم expiresIn المتاحة:

القيمة	المدة
30d	30 يوماً
60d	60 يوماً
90d	90 يوماً
1y	سنة واحدة
never	بدون انتهاء صلاحية

تتضمن الاستجابة كلاً من المفتاح الخام والبيانات الوصفية للمفتاح:

{
  "data": {
    "key": "dm_live_a1b2c3d4e5f6...",
    "apiKey": {
      "id": "key-abc123",
      "userId": "user_789",
      "name": "Production Server",
      "prefix": "dm_live_a1b2c3d4",
      "expiresAt": "2025-10-13T12:00:00.000Z",
      "lastUsedAt": null,
      "createdAt": "2025-07-15T12:00:00.000Z",
      "revoked": false
    }
  }
}

WARNING

حقل key في الاستجابة هو المرة الوحيدة التي يُرجع فيها مفتاح API الخام. خزّنه في مكان آمن (مثال: متغير بيئة أو مدير أسرار) فوراً. إذا فقدته، ستحتاج إلى إنشاء مفتاح جديد.

إدراج المفاتيح

استرجع جميع مفاتيح API النشطة (غير الملغاة) لحسابك:

curl

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

TypeScript

const response = await fetch("https://api.docmap.io/v1/api-keys", {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const { data } = await response.json();

data.forEach((key) => {
  console.log(`${key.name} (${key.prefix}...) - Last used: ${key.lastUsedAt ?? "Never"}`);
});

Python

response = requests.get(
    "https://api.docmap.io/v1/api-keys",
    headers={"Authorization": f"Bearer {api_key}"},
)

for key in response.json()["data"]:
    last_used = key["lastUsedAt"] or "Never"
    print(f"{key['name']} ({key['prefix']}...) - Last used: {last_used}")

تتضمن الاستجابة البيانات الوصفية لكل مفتاح لكنها لا تتضمن أبداً قيمة المفتاح الكاملة -- فقط prefix (أول 16 حرفاً) يُعرض:

{
  "data": [
    {
      "id": "key-abc123",
      "userId": "user_789",
      "name": "Production Server",
      "prefix": "dm_live_a1b2c3d4",
      "expiresAt": "2025-10-13T12:00:00.000Z",
      "lastUsedAt": "2025-07-15T14:30:00.000Z",
      "createdAt": "2025-07-15T12:00:00.000Z",
      "revoked": false
    }
  ]
}

تدوير المفاتيح

لتدوير مفتاح API دون توقف، اتبع هذه الخطوات:

1. أنشئ مفتاحاً جديداً باسم وصفي يشير إلى أنه بديل
2. حدّث أنظمتك (متغيرات البيئة ومدير الأسرار وCI/CD) لاستخدام المفتاح الجديد
3. تحقق من أن المفتاح الجديد يعمل بشكل صحيح بإجراء استدعاء API تجريبي
4. ألغِ المفتاح القديم بعد تحديث جميع الأنظمة

// Step 1: Create the new key
const createResponse = await fetch("https://api.docmap.io/v1/api-keys", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${currentApiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Production Server (rotated 2025-07)",
    expiresIn: "90d",
  }),
});

const { data: newKeyData } = await createResponse.json();
const newKey = newKeyData.key;

// Step 2: Verify the new key works
const testResponse = await fetch("https://api.docmap.io/v1/usage", {
  headers: { Authorization: `Bearer ${newKey}` },
});

if (testResponse.ok) {
  console.log("New key verified. Update your environment variables now.");

  // Step 3: Revoke the old key (after updating systems)
  // await fetch(`https://api.docmap.io/v1/api-keys/${oldKeyId}`, {
  //   method: "DELETE",
  //   headers: { Authorization: `Bearer ${newKey}` },
  // });
}

TIP

أبقِ كلا المفتاحين نشطين خلال فترة الانتقال. ألغِ المفتاح القديم فقط بعد التأكد من أن جميع الأنظمة تستخدم المفتاح الجديد.

إلغاء المفاتيح

ألغِ مفتاح API بإرسال طلب DELETE مع معرّف المفتاح. يتوقف المفتاح عن العمل فوراً.

curl

curl -X DELETE https://api.docmap.io/v1/api-keys/key-abc123 \
  -H "Authorization: Bearer dm_live_your_api_key"

TypeScript

const response = await fetch("https://api.docmap.io/v1/api-keys/key-abc123", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${apiKey}` },
});

const result = await response.json();
console.log("Revoked:", result.success); // true

Python

response = requests.delete(
    "https://api.docmap.io/v1/api-keys/key-abc123",
    headers={"Authorization": f"Bearer {api_key}"},
)

print("Revoked:", response.json()["success"])  # True

WARNING

الإلغاء فوري ودائم. أي طلب يستخدم المفتاح الملغى سيتلقى خطأ 401 UNAUTHORIZED. تأكد من عدم وجود أنظمة نشطة تعتمد على المفتاح قبل إلغائه.

مراقبة الاستخدام

يتتبع كل مفتاح API طابع زمني lastUsedAt يُحدّث تلقائياً كلما استُخدم المفتاح لمصادقة طلب. استخدم نقطة نهاية القائمة لمراقبة آخر نشاط لمفاتيحك:

const response = await fetch("https://api.docmap.io/v1/api-keys", {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const { data: keys } = await response.json();

// Find keys that haven't been used in over 30 days
const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);

keys.forEach((key) => {
  if (!key.lastUsedAt || new Date(key.lastUsedAt) < thirtyDaysAgo) {
    console.log(`Key "${key.name}" (${key.prefix}...) is inactive — consider revoking it`);
  }
});

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

• استخدم أسماء وصفية. سمِّ المفاتيح حسب الغرض أو البيئة: "Production API" أو "Staging" أو "GitHub Actions CI". هذا يسهّل تحديد أي مفتاح يجب إلغاؤه إذا تم اختراقه.

• حدد تواريخ انتهاء الصلاحية. فضّل 90d أو 1y على never. المفاتيح المنتهية الصلاحية تفرض التدوير المنتظم، مما يحد من نافذة التعرض إذا تم تسريب مفتاح.

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

• دوّر بانتظام. حتى مع تواريخ انتهاء الصلاحية، دوّر المفاتيح بشكل استباقي -- خاصة بعد مغادرة أعضاء الفريق أو تغييرات البنية التحتية.

• لا تسجّل المفاتيح الخام أبداً. تجنب طباعة مفاتيح API في سجلات التطبيق أو تقارير الأخطاء أو مخرجات وحدة التحكم. استخدم حقل prefix عندما تحتاج للإشارة إلى مفتاح في السجلات.

• استخدم متغيرات البيئة. خزّن المفاتيح في متغيرات البيئة أو مدير أسرار. لا تكتبها مباشرة في الكود المصدري أو ترفعها إلى نظام التحكم بالإصدارات.