إنتقل إلى المحتوى الرئيسي

المصادقة لأدوات API

معظم واجهات API الحقيقية تحتاج بيانات اعتماد. موفّرو المصادقة في Orki يتيحون لك تخزين بيانات الاعتماد مرة واحدة — مفتاح API أو عميل OAuth2 — وإرفاقها بأي أداة API أو خطوة في مسار عمل. في كل استدعاء، يحقن Orki بيانات الاعتماد على الخادم، قبل مغادرة الطلب للمنصة مباشرة.

الجزء المهم: الوكيل الذكي لا يرى بيانات الاعتماد أبداً. فهي ليست في مخطط الأداة، ولا في التعليمات، ولا في الاستجابة اللي يقرؤها الوكيل. الأسرار مشفّرة أثناء التخزين.

بالنسبة لـ Balloon Bliss، واجهة API طلبات المحل تتطلب مفتاح API — راح نخزّنه كموفّر اسمه balloon_orders_key ونرفقه بأداة order_status_lookup.

أين تجدها​

التكاملات ← المصادقة في الشريط الجانبي.

Authentication list

كل بطاقة تعرض نوع بيانات الاعتماد وأين تُحقن. اضغط على New authentication لإنشاء واحدة.

نوعان من بيانات الاعتماد​

النوعكيف يعملاستخدمه لـ
مفتاح API ثابتسر ثابت يُحقن في ترويسة أو معامل استعلام في كل استدعاء.واجهات API بنمط X-Api-Key، ورموز الوصول الشخصية.
OAuth2 client credentialsيستبدل Orki معرّف العميل + السر برمز bearer من رابط الرموز عند الموفّر، ويخزّنه مؤقتاً، ويجدّده قبل انتهاء صلاحيته، ويحقن Authorization: Bearer ….واجهات API للشركاء بتدفق OAuth2 من نوع client_credentials.

مثال 1 — مفتاح API ثابت​

  1. الاسم — balloon_orders_key. تسمية داخلية (بصيغة snake_case)؛ الوكيل لا يراها أبداً.
  2. اختر بطاقة مفتاح API الثابت.
  3. الحقن في — Header، اسم الترويسة — X-Api-Key.
  4. قيمة المفتاح — الصق السر.
  5. بادئة القيمة الاختيارية — مثل Bearer إذا كانت الواجهة تتوقع Authorization: Bearer <key>.

المعاينة في الأسفل تعرض بالضبط ما سيُضاف إلى كل استدعاء — مثل Header: X-Api-Key = ••••••.

Static API key form

اضغط على حفظ.

مثال 2 — OAuth2 Client Credentials​

لنفترض أن Balloon Bliss تكاملت لاحقاً مع شريك شحن واجهته تستخدم OAuth2:

  1. الاسم — shipping_partner_oauth، واختر بطاقة OAuth2 client credentials.
  2. رابط الرمز (Token URL) — نقطة نهاية الرموز عند الشريك (مثل https://api.shipping-partner.example/oauth/token).
  3. معرّف العميل / سر العميل — من الشريك.
  4. النطاق (Scope) (اختياري) — مفصول بمسافات، مثل shipments.read shipments.write.
  5. إرسال بيانات الاعتماد كـ — Form (الافتراضي) أو JSON، حسب ما تتوقعه نقطة نهاية الرموز.

OAuth2 client credentials form

يغطي قسم الإعدادات المتقدمة الموفّرين غير القياسيين: من أين يُقرأ الرمز من الاستجابة (JSONPath)، والتعامل مع انتهاء الصلاحية، والحقن المخصص، وحقول إضافية لطلب الرمز. الإعدادات الافتراضية تناسب تدفق OAuth2 القياسي.

تُخزَّن الرموز مؤقتاً وتُجدَّد تلقائياً — أدوات API عندك لا تتعامل مع انتهاء الصلاحية إطلاقاً.

الإرفاق بأداة​

افتح الأداة (التكاملات ← واجهات API ← تعديل) واختر الموفّر في قسم المصادقة الخاص بها:

Tool with auth provider attached

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

ملاحظات أمنية​

  • الأسرار مشفّرة أثناء التخزين ولا تُفك إلا لحظة الاستدعاء الخارج.
  • مخطط الأداة الظاهر للوكيل ونتائجها لا يحملان أي أثر لبيانات الاعتماد — محاولة حقن التعليمات (prompt injection) لا تقدر تطلب من الوكيل كشف ما لم يملكه أصلاً.
  • فضّل الموفّر على لصق المفاتيح في حقول ترويسات الأداة: قيم الترويسات تعيش في إعدادات الأداة، بينما أسرار الموفّر تصبح للكتابة فقط بعد الحفظ.

استكشاف الأخطاء وحلها​

  • ‏401/403 من واجهة API الخارجية — المفتاح خاطئ أو تنقصه الصلاحيات؛ عدّل الموفّر وأعد إدخال قيمة المفتاح.
  • استدعاءات أداة OAuth2 تفشل بعد أن كانت تعمل — تحقق أن رابط الرمز ما زال متاحاً وأن العميل لم يُلغَ؛ يجلب Orki رمزاً جديداً تلقائياً بمجرد رفض الرمز المخزَّن أو انتهاء صلاحيته.
  • أي الأدوات تستخدم هذا الموفّر؟ افتح قسم المصادقة في كل أداة — حذف موفّر ما زال مرفقاً سيعطّل استدعاءات تلك الأدوات.

الخطوات التالية​