إنشاء مفتاح API

POST /v1/api-keys

إنشاء مفتاح API جديد للمصادقة مع DocMap API. يمكن لكل مستخدم أن يمتلك حتى 10 مفاتيح API نشطة (غير ملغاة).

جرّبه

اختبر هذا الـ endpoint بشكل تفاعلي في Swagger UI.

المصادقة مطلوبة

أدرج مفتاح API في ترويسة Authorization.

الطلب

الترويسات

الترويسة	القيمة	مطلوب
Authorization	Bearer <token>	نعم
Content-Type	application/json	نعم

الجسم

الحقل	النوع	مطلوب	الوصف
name	string	نعم	تسمية وصفية للمفتاح (1--100 حرف).
expiresIn	string	نعم	فترة انتهاء الصلاحية: "30d" أو "60d" أو "90d" أو "1y" أو "never".

أمثلة الكود

curl

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

TypeScript

const apiKey = process.env.DOCMAP_API_KEY

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

const { data } = await response.json()

// IMPORTANT: Store the key immediately — it cannot be retrieved later
console.log('API Key:', data.key)
console.log('Key ID:', data.apiKey.id)

Python

import requests

api_key = "dm_live_abc123def456ghi789jkl012mno345"

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

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

# IMPORTANT: Store the key immediately — it cannot be retrieved later
print(f"API Key: {data['key']}")
print(f"Key ID: {data['apiKey']['id']}")

الاستجابة

الحالة: 201 Created

جسم الاستجابة مغلف في كائن data.

WARNING

قيمة المفتاح الخام تُرجع فقط في هذه الاستجابة. خزّنه بشكل آمن فوراً -- لا يمكن استرجاعه لاحقاً.

الحقول

الحقل	النوع	الوصف
key	string	مفتاح API الخام (مثال: dm_live_abc123def456ghi789jkl012mno345). يُعرض مرة واحدة فقط.
apiKey	object	كائن البيانات الوصفية للمفتاح (انظر أدناه).

كائن apiKey:

الحقل	النوع	الوصف
id	string	معرّف فريد لمفتاح API.
userId	string	معرّف المستخدم الذي يملك المفتاح.
name	string	تسمية وصفية للمفتاح.
prefix	string	الأحرف الأولى من المفتاح للتعريف (مثال: dm_live_abc1).
expiresAt	string | null	طابع زمني ISO 8601 لانتهاء الصلاحية، أو null إذا كان المفتاح لا ينتهي أبداً.
lastUsedAt	string | null	طابع زمني ISO 8601 لآخر مرة استُخدم فيها المفتاح. null إذا لم يُستخدم أبداً.
createdAt	string	طابع زمني ISO 8601 لوقت إنشاء المفتاح.
revoked	boolean	ما إذا كان المفتاح قد تم إلغاؤه. دائماً false لمفتاح مُنشأ حديثاً.

مثال

{
  "data": {
    "key": "dm_live_r4nd0mK3yV4lu3x9w8v7u6t5s4q3p2n1m0l9k8j7",
    "apiKey": {
      "id": "ak_1a2b3c4d5e6f7g8h",
      "userId": "uid_a1b2c3d4e5f6",
      "name": "Production Server",
      "prefix": "dm_live_r4nd",
      "expiresAt": "2025-02-18T10:00:00.000Z",
      "lastUsedAt": null,
      "createdAt": "2024-11-20T10:00:00.000Z",
      "revoked": false
    }
  }
}

الأخطاء

الحالة	الرمز	الوصف
400	MAX_KEYS_REACHED	لقد وصلت إلى الحد الأقصى وهو 10 مفاتيح API نشطة. ألغِ مفتاحاً موجوداً قبل إنشاء مفتاح جديد.
401	UNAUTHORIZED	مفتاح API / رمز مفقود أو غير صالح أو منتهي الصلاحية.