تطبيقات OAuth
مفتاح API يؤتمت حسابك أنت. أما إن كنت تبني منتجًا يجدول لحسابات شارك أخرى، فاستخدم OAuth بدلًا من ذلك: يوافقون على تطبيقك في شاشة تصريح من شارك، فتحصل على رمز وصول يتصرف نيابةً عنهم. ولا تلمس مفتاحهم أبدًا. ولربط أداة الذكاء الاصطناعي الخاصة بك لا تحتاج إلى تطبيق أصلًا: اتبع ربط أداة الذكاء الاصطناعي.
ورمز OAuth يصل إلى العمليات نفسها تمامًا التي يصل إليها مفتاح API، وصفحة نظرة عامة على API تشرح العنوان الأساسي والحدود وأشكال الأخطاء المشتركة بينهما.
التدفق
Section titled “التدفق”- يضغط أحد مستخدمي منتجك زر «ربط شارك» عندك.
- ترسله إلى شاشة التصريح في شارك بمعرف عميلك.
- يعرض شارك شاشة تصريح تسمي تطبيقك، فيوافق أو يرفض.
- يعيده شارك إلى رابط إعادة التوجيه عندك ومعه
codeقصير العمر. - يبادل خادمك رمز التفويض ذلك برمز وصول.
- تستدعي API برمز الوصول.
الخطوتان 2 و4 تجريان في متصفحه. والخطوة 5 تجري على خادمك، لأنها تحتاج السر الخاص بعميلك.
تسجيل تطبيقك
Section titled “تسجيل تطبيقك”يمكن لكل مؤسسة أن تملك تطبيق OAuth واحدًا، وإدارته تتطلب دور مشرف أو مشرف عام في حساب يتيح الوصول إلى API. ومن يفتح تبويب التطبيقات غير هؤلاء لا يرى إلا التطبيقات المصرح لها.
افتح شارك، واذهب إلى الإعدادات، ثم تبويب التطبيقات.
-
أنشئ تطبيقًا. تقدم اسم التطبيق (يظهر على شاشة التصريح)، والوصف وصورة الملف الشخصي اختياريًا، ورابط إعادة التوجيه الذي يعيد شارك الناس إليه بعد أن يقرروا.
-
يصدر شارك معرف العميل مسبوقًا بـ
pca_والسر الخاص بالعميل مسبوقًا بـpcs_.
أرسل الناس ليصرحوا
Section titled “أرسل الناس ليصرحوا”أعد توجيههم إلى شاشة التصريح في شارك:
https://dash.sharek.app/oauth/authorize?client_id=pca_your_client_id&response_type=code&state=random-string| المعامل | مطلوب | الوصف |
|---|---|---|
client_id |
نعم | معرف العميل الخاص بتطبيقك. |
response_type |
نعم | يجب أن يكون code. |
state |
لا | نص عشوائي تولده لكل محاولة. وينصح به بشدة: فهو ما تكشف به استدعاءً مزورًا. |
يرون اسم تطبيقك ووصفه وصورته، ويختارون تصريح أو رفض.
عالج الاستدعاء الراجع
Section titled “عالج الاستدعاء الراجع”يعيدهم شارك إلى رابط إعادة التوجيه المسجل عندك.
عند الموافقة:
https://your-app.example/callback?code=the-code&state=random-stringعند الرفض:
https://your-app.example/callback?error=access_denied&state=random-stringقارن state العائد بالذي أنشأته قبل أن تفعل أي شيء آخر. فإن لم يتطابق، فتجاهل الطلب.
بادل الرمز برمز وصول
Section titled “بادل الرمز برمز وصول”من جهة الخادم، لأن هذا الاستدعاء يحمل سرك:
curl -X POST https://dash.sharek.app/api/oauth/token \ -H "Content-Type: application/json" \ -d '{ "grant_type": "authorization_code", "code": "the-code-from-the-callback", "client_id": "pca_your_client_id", "client_secret": "pcs_your_client_secret" }'| الحقل | مطلوب | الوصف |
|---|---|---|
grant_type |
نعم | يجب أن يكون authorization_code. |
code |
نعم | رمز التفويض الآتي من الاستدعاء الراجع. |
client_id |
نعم | معرف العميل الخاص بتطبيقك. |
client_secret |
نعم | السر الخاص بعميل تطبيقك. |
ويمكنك إرسال client_id وclient_secret في ترويسة Authorization: Basic بدلًا من ذلك،
بترميز base64 لـ client_id:client_secret، ثم حذفهما من جسم الطلب.
والتبادل الناجح يجيب بـ 200:
{ "id": "organization-id", "cus": "billing-customer-id", "access_token": "pos_your_oauth_token", "token_type": "bearer", "scope": "mcp:read mcp:write"}| الحقل | الوصف |
|---|---|
id |
المؤسسة التي يتصرف رمز الوصول نيابةً عنها. احفظه بجانب رمز الوصول. |
cus |
معرف عميل الفوترة لتلك المؤسسة. |
access_token |
رمز الوصول، مسبوقًا بـ pos_. |
token_type |
دائمًا bearer. |
scope |
دائمًا mcp:read mcp:write للتطبيق الذي تسجله. وهو للعلم فقط: فرمز الوصول يصل إلى كل عملية في واجهة API العامة أيًا كان ما يقوله. |
استدع API برمز الوصول
Section titled “استدع API برمز الوصول”الترويسة نفسها كمفتاح API، وما زالت بلا بادئة Bearer رغم أن token_type يقول bearer:
curl -H "Authorization: pos_your_oauth_token" \ https://dash.sharek.app/api/public/v1/integrationsوأول استدعاء مناسب هو جلب الحساب الحالي: فهو يسمي الشخص الذي وافق على تطبيقك ومؤسسته، لتعرض من المتصل.
ورموز الوصول لا تنتهي بمؤقت. بل تتوقف عن العمل حين يسحب الشخص تطبيقك، أو حين تحذفه أنت.
إدارة تطبيقك
Section titled “إدارة تطبيقك”تدوير السر إن تسرب. فالسر القديم يتوقف عن العمل فورًا. ورموز الوصول القائمة تبقى تعمل، لأن السر لا يستخدمه إلا تبادل الرموز.
حذف التطبيق يسحب كل رمز أصدره يومًا، ويختفي من التطبيقات المصرح لها عند الجميع. ولا تراجع عن ذلك.
الأخطاء
Section titled “الأخطاء”| الخطأ | متى | الحالة | المعنى |
|---|---|---|---|
access_denied |
في الاستدعاء الراجع | لا يوجد | اختار رفض. وليس خطأً يستدعي إعادة المحاولة. |
invalid_client |
تبادل الرموز | 401 |
معرف العميل أو السر خاطئ أو مفقود. |
invalid_grant |
تبادل الرموز | 400 |
رمز التفويض مجهول، أو استخدم من قبل، أو يخص تطبيقًا آخر. |
invalid_grant مع error_description: "Code has expired" |
تبادل الرموز | 400 |
مضى أكثر من 10 دقائق. أعد بدء التدفق. |
unsupported_grant_type |
تبادل الرموز | 400 |
grant_type لم يكن authorization_code. |