المصادقة

الغرض من المفتاح

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

يتضمن كل طلب مفتاح API. أنشئه من شاشة مفاتيح API في حسابك؛ يظهر مرة واحدة عند الإنشاء ولا يُحفظ بصيغة مقروءة مطلقًا.

X-PDFgine-Key: pdfgine_live_xxxxxxxxxxxxxxxxxxxxxxxx

لا تضمّن المفتاح في متصفح أو تطبيق جوال أبدًا. نفّذ الاستدعاءات من خادمك.

يحمل كل مفتاح مجموعة نطاقات، لذا لا يمكن لمفتاح ينشئ المستندات فقط تعديل القوالب.

templates:read   templates:write   documents:render
previews:manage  assets:read       assets:write
usage:read       api-keys:manage

استدعاء يعمل وآخر لا يعمل

يسرد الاستدعاء الأول قوالبك. ويرسل الثاني مفتاحًا أُلغي، وتوضح الاستجابة ذلك تحديدًا.

# يوضع المفتاح في البيئة لا في الشيفرة
export PDFGINE_KEY="pdfgine_live_..."

curl -i https://api.pdfgine.com/api/v1/templates \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
  "title": "Unauthorized request",
  "status": 401,
  "detail": "The API key is invalid.",
  "correlationId": "0123b82d0a59e8b196a783af0e0e86bc"
}

يتضمن كل محتوى خطأ correlationId. اذكرها عند مراسلة الدعم ليُعثر على الطلب في السجلات دون تخمين.

الأخطاء الشائعة

• يوضع المفتاح في ترويسة X-PDFgine-Key. لا يُقرأ رمز Authorization: Bearer أصلًا، فيجيب الاستدعاء بالحالة 401 حتى لو كان المفتاح صالحًا.
• تختلف 401 عن 403. تعني 401 «لا أعرف هويتك»، وتعني 403 «أعرفك لكن هذا المفتاح لا يملك هذا النطاق»؛ فلا يمكن لمفتاح دون templates:write حفظ قالب. تُحدد النطاقات عند إنشاء المفتاح.
• تظهر القيمة السرية مرة واحدة. إذا فُقدت فلا يمكن قراءتها مجددًا؛ ألغِ المفتاح وأنشئ آخر.
• لا مكان للمفتاح في متصفح أو تطبيق جوال مطلقًا. يمكن قراءة أي شيء يُرسل إلى جهاز؛ استدعِ PDFgine من خادمك.
• يسري الإلغاء من الاستدعاء التالي مباشرة. انشر المفتاح الجديد أولًا ثم ألغِ القديم، وإلا فشلت الاستدعاءات الجارية.