المصادقة لأدوات API
معظم واجهات API الحقيقية تحتاج بيانات اعتماد. موفّرو المصادقة في Orki يتيحون لك تخزين بيانات الاعتماد مرة واحدة وإرفاقها بأي أداة API أو خطوة في مسار عمل. في كل استدعاء، يحقن Orki بيانات الاعتماد على الخادم، قبل مغادرة الطلب للمنصة مباشرة.
الجزء المهم: الوكيل الذكي لا يرى بيانات الاعتماد أبداً. فهي ليست في مخطط الأداة، ولا في التعليمات، ولا في الاستجابة اللي يقرؤها الوكيل. الأسرار مشفّرة أثناء التخزين وتصير للكتابة فقط بعد الحفظ.
بالنسبة لـ Balloon Bliss، واجهة API طلبات المحل تتطلب مفتاح API — راح نخزّنه كموفّر اسمه balloon_orders_key ونرفقه بأداة order_status_lookup.
أين تجدها
التكاملات ← المصادقة في الشريط الجانبي.
كل بطاقة تعرض نوع بيانات الاعتماد وأين تُحقن. اضغط على New authentication لإنشاء واحدة.
ثلاثة أنواع من بيانات الاعتماد
| النوع | كيف يعمل | استخدمه لـ |
|---|---|---|
| مفتاح API ثابت | سر ثابت يُحقن في ترويسة أو معامل استعلام في كل استدعاء. | واجهات API بنمط X-Api-Key، ورموز الوصول الشخصية. |
| OAuth2 client credentials | يستبدل Orki معرّف العميل + السر برمز bearer من رابط الرموز عند الموفّر، ويخزّنه مؤقتاً، ويجدّده قبل انتهاء صلاحيته، ويحقن Authorization: Bearer …. | واجهات API للشركاء بتدفق OAuth2 من نوع client_credentials. |
| WS-Security (SOAP) | تُدرج كتلة <wsse:Security> من نوع UsernameToken في ترويسة مغلّف SOAP في كل استدعاء. | خدمات SOAP القديمة — الأنظمة البنكية الأساسية، وتزويد خدمات الاتصالات، ونقاط نهاية ERP. |
الثلاثة تبدأ بنفس الطريقة: اسم (snake_case، داخلي فقط — الوكيل ما يشوفه) ووصف اختياري.
مثال ١ — مفتاح API ثابت
- الاسم —
balloon_orders_key. - اختر بطاقة مفتاح API الثابت.
- الحقن في —
Header، اسم الترويسة —X-Api-Key. - قيمة المفتاح — الصق السر.
- بادئة القيمة الاختيارية — مثل
Bearerإذا كانت الواجهة تتوقعAuthorization: Bearer <key>.
النص المساعد تحت حقل البادئة يعرض القالب الناتج مباشرةً، والمعاينة في الأسفل تعرض بالضبط ما سيُضاف إلى كل استدعاء.
اضغط حفظ.
مثال ٢ — OAuth2 Client Credentials
لنفترض أن Balloon Bliss تكاملت لاحقاً مع شريك شحن واجهته تستخدم OAuth2:
- الاسم —
shipping_partner_oauth، واختر بطاقة OAuth2 client credentials. - رابط الرمز (Token URL) — نقطة نهاية الرموز عند الشريك (مثل
https://api.shipping-partner.example/oauth/token). - معرّف العميل / سر العميل — من الشريك.
- النطاق (Scope) (اختياري) — مفصول بمسافات، مثل
shipments.read shipments.write. - إرسال بيانات الاعتماد كـ —
Form(الافتراضي) أوJSON، حسب ما تتوقعه نقطة نهاية الرموز.
الرموز تُجلب وتُخزَّن مؤقتاً وتُجدَّد تلقائياً — أدوات API عندك ما تتعامل مع انتهاء الصلاحية إطلاقاً.
قسم الإعدادات المتقدمة
الإعدادات الافتراضية تناسب موفّر OAuth2 قياسي. افتح الإعدادات المتقدمة لمّا يكون موفّرك غير قياسي:
| الحقل | الغرض | الافتراضي |
|---|---|---|
| Token JSONPath | مكان الرمز داخل الاستجابة. | access_token |
| Expiry JSONPath | مكان مدة الصلاحية (بالثواني). | expires_in |
| Fallback TTL (s) | مدة التخزين المؤقت لمّا ما تحمل الاستجابة مدة صالحة. | 1800 |
| Safety margin (s) | تُخصم من المدة عشان ما ينتهي الرمز في منتصف الطلب. | 30 |
| Inject into / Injection name | وين يروح الرمز في الاستدعاء الخارج. | Header / Authorization |
| Injected value template | القيمة المكتوبة فيه. لازم تحتوي {{token}}. | Bearer {{token}} |
| Extra token-request headers | تُضاف عند جلب الرمز — مثل Accept: application/json. | لا شيء |
| Custom token-request body | يستبدل الجسم المُولَّد بالكامل. استخدمه للمعاملات غير القياسية مثل audience. أشر لأسرارك بـ {{secret.clientId}}. | لا شيء |
| Refresh token + retry once on a 401 | عند استقبال 401 من واجهتك: تجاهل الرمز المخزّن، اجلب واحداً جديداً، وأعد الاستدعاء مرة واحدة. | مُفعّل |
مرجع المصادقة يوثّق الطلب الدقيق اللي يرسله Orki، والحقول اللي يقرأها، وقواعد التخزين المؤقت وإعادة المحاولة — مكتوب للمهندس اللي يملك الواجهة المُستدعاة.
مثال ٣ — WS-Security (SOAP)
لخدمة SOAP تتوقع UsernameToken:
- سمّها، وبعدين اختر بطاقة WS-Security (SOAP).
- اسم المستخدم وكلمة المرور.
- افتح الإعدادات المتقدمة لو كانت الخدمة صعبة الإرضاء:
| الحقل | الغرض | الافتراضي |
|---|---|---|
| Password mode | PasswordText يرسل كلمة المرور كما هي (الأكثر شيوعاً). PasswordDigest يرسل بدلها بصمة مُجزّأة مع nonce وطابع زمني جديدين — فما يعبر السلك شيء قابل لإعادة الاستخدام. | PasswordText |
| Include timestamp | يضيف wsu:Timestamp بنافذة إنشاء/انتهاء. | مُفعّل |
| Timestamp validity (s) | طول تلك النافذة. المدى المقبول ٣٠–٣٦٠٠. | 300 |
mustUnderstand="1" على ترويسة Security | يخبر الخدمة أنها ملزمة بمعالجة الترويسة أو رفض الرسالة. | مُفعّل |
هذا النوع يحقن في مغلّف SOAP، مو في ترويسة أو معامل استعلام. الأداة اللي ترفقه فيها لازم تستخدم نوع الجسم text/xml (SOAP) وترسل soapenv:Envelope صالحاً — SOAP 1.1 أو 1.2. ولو أُرفق بأداة JSON، يفشل الاستدعاء برسالة «WS-Security requires a SOAP XML request body.»
ولأن بيانات الاعتماد تروح في الجسم، فحقول Inject into / Injection name ما تنطبق وما تظهر.
اختبار الموفّر
احفظ الموفّر أولاً، وبعدين افتحه من جديد — يظهر في الترويسة زر اختبار.
| النتيجة | المعنى |
|---|---|
| Token OK | مفتاح ثابت أو WS-Security: الأسرار المخزّنة تُفك بشكل صحيح. |
| Token OK · expires … | OAuth2: استدعى Orki فعلاً نقطة نهاية الرموز عندك واستلم رمزاً. |
| سطر خطأ أحمر | الرسالة جاية من الموفّر عندك. راجع قسم استكشاف الأخطاء في آخر الصفحة. |
ما فيه زر اختبار أثناء الإنشاء. احفظ، وافتح من القائمة، وبعدين اختبر. وعند إعادة الفتح تظهر حقول الأسرار كـ •••••• (unchanged) — اتركها فارغة عشان تبقي القيمة المخزّنة.
الإرفاق بأداة
افتح الأداة (التكاملات ← واجهات API، ثم عدّلها) وانزل لقسم Authentication — يقع مباشرة تحت Headers وفوق جسم الطلب.
القائمة المنسدلة تقرأ None — no authentication افتراضياً. اختر موفّرك واحفظ.
هذا كل شيء. كل تنفيذ لهذه الأداة — سواء استدعاها الوكيل مباشرة أو شغّلتها خطوة في مسار عمل — يخرج الآن وبيانات الاعتماد محقونة فيه. موفّر واحد يقدر يخدم أي عدد من الأدوات، وتدوير السر في مكان واحد يحدّثها كلها.
رابط ＋ New جنب القائمة يفتح نموذج الموفّر كصفحة كاملة. أداتك نصف المعبّأة تُحفظ كمسودة، لكن الأسلس أنك تنشئ الموفّر أولاً وبعدين تبني الأداة.
في باني مسارات العمل، عقدة الأداة اللي تحمل موفّراً تعرض أيقونة قفل خضراء صغيرة.
ملاحظات أمنية
- الأسرار مشفّرة أثناء التخزين ولا تُفك إلا لحظة الاستدعاء الخارج.
- بعد الحفظ، السر يصير للكتابة فقط. قراءة الموفّر — من الواجهة أو عبر API — ترجع
********، ولا ترجع أبداً القيمة ولا شكلها المشفّر. - مخطط الأداة الظاهر للوكيل ونتائجها لا يحملان أي أثر لبيانات الاعتماد، فمحاولة حقن التعليمات (prompt injection) ما تقدر تطلب من الوكيل كشف ما لم يملكه أصلاً.
- فضّل الموفّر على لصق المفاتيح في حقول ترويسات الأداة: قيم الترويسات تعيش في إعدادات الأداة على المكشوف، أما أسرار الموفّر فلا.
- روابط الرموز لازم تكون نطاقات عامة. عناوين IP و
localhostمرفوضة.
استكشاف الأخطاء وحلها
| العَرَض | السبب | الحل |
|---|---|---|
الاختبار يقول Token endpoint returned HTTP 401 | معرّف العميل أو السر خطأ، أو نقطة النهاية تبغاهما في مكان ثاني. | أعد إدخال الاثنين. وإذا كان الموفّر يتوقع HTTP Basic بدل حقول النموذج، راجع المرجع. |
الاختبار يقول TokenPath 'access_token' not found | الرمز مو في المسار الافتراضي. | اضبط Token JSONPath في الإعدادات المتقدمة ليطابق الاستجابة الحقيقية، مثل data.token. |
| الاختبار يقول إن الاستجابة ليست JSON صالحاً | نقطة نهاية الرموز ترجع XML أو بيانات form-encoded. | نوع OAuth2 في Orki يتطلب استجابة رمز بصيغة JSON. |
| استدعاءات الأداة ترجع خطأ خادم، لكن الاختبار ينجح | فيه شي ثاني في الأداة يفشل. | استخدم درج اختبار الخاص بالأداة — يعرض مرحلة المسار والرسالة الأصلية. |
| أخطاء 401 من الواجهة رغم أن الرمز صالح | المخطط خطأ. | راجع Injected value template — بعض الواجهات تبغى Token {{token}} مو Bearer {{token}}. |
| كانت تشتغل وبعدين بدأت تفشل | العميل أُلغي، أو السر دُوّر عند الموفّر. | أعد إدخال السر واضغط اختبار. يجلب Orki رمزاً جديداً تلقائياً بمجرد رفض المخزَّن. |
| خدمة SOAP ترفض المغلّف | وضع كلمة مرور خاطئ، أو مشكلة ساعة/طابع زمني. | جرّب PasswordDigest، ووسّع Timestamp validity. |
| أي الأدوات تستخدم هذا الموفّر؟ | — | افحص قسم Authentication في كل أداة. حذف موفّر ما زال مرفقاً سيعطّل استدعاءات تلك الأدوات. |
الخطوات التالية
- مرجع المصادقة — العقد الدقيق، للفريق اللي يملك الواجهة
- إنشاء أدوات API — ابنِ الأدوات اللي تستخدم بيانات الاعتماد هذه
- بناء مسارات العمل — اربط الأدوات الموثَّقة في تدفقات