OAuth 2.0

استخدم OAuth عندما يثبت التاجر تطبيقك. يختار التاجر متجرًا ويوافق على النطاقات الدقيقة؛ ويحصل backend على رموز لذلك التثبيت فقط.

مسار التفويض

تطبيق المطور
     ↓ يفتح التاجر التثبيت
موافقة SaaS OAuth
     ↓ يختار المتجر ويوافق على النطاقات
Authorization Code
     ↓ redirect URI دقيق + state
Backend المطور
     ↓ code + PKCE verifier + بيانات التطبيق
Token Exchange
     ↓
Access Token + Refresh Token
     ↓
SaaS API

قبل البدء

أنشئ التطبيق والإصدار من لوحة المطور ← التطبيقات. سجّل callback الدقيق، واختر النطاقات، واحفظ Client Secret الذي يظهر مرة واحدة في backend. أنشئ state وPKCE verifier جديدين لكل تثبيت.

طلب التفويض

وجّه متصفح التاجر إلى:

GET https://getsas.xyz/api/oauth/authorize

يسجل التاجر الدخول ويختار متجرًا مؤهلًا ثم يوافق أو يرفض. مجرد فتح الصفحة لا يمنح أي صلاحية.

استبدال الرمز

استدعِ token endpoint من backend فقط:

curl --request POST 'https://getsas.xyz/api/oauth/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "grant_type": "authorization_code",
    "client_id": "<CLIENT_ID>",
    "client_secret": "<CLIENT_SECRET>",
    "code": "<AUTHORIZATION_CODE>",
    "redirect_uri": "https://app.example.com/oauth/callback",
    "code_verifier": "<PKCE_VERIFIER>"
  }'

تحقق من state قبل الاستبدال. يستخدم code مرة واحدة وينتهي سريعًا. يجب أن يطابق redirect URI والـ verifier طلب التفويض تمامًا.

الرموز والتجديد والتدوير

• مدة access token هي 15 دقيقة.
• مدة refresh token الدوار هي 30 يومًا.
• احفظ الرموز مشفرة في الخادم واحذفها من السجلات.
• إعادة استخدام refresh token تلغي عائلة الرموز.
• عند تدوير Client Secret يبقى السابق صالحًا 24 ساعة (انظر أدناه).
• إلغاء التثبيت أو التعليق أو فقدان صلاحية التاجر يلغي السلطة المشتقة.

جدّد باستخدام grant_type=refresh_token وclient_id وclient_secret وأحدث refresh_token. احفظ الرمز الجديد ذريًا قبل حذف القديم.

إلغاء الرموز

عندما يفصل التاجر تكاملك، أو لم تعد بحاجة إلى رمز، ألغِه من backend (وفق RFC 7009):

POST https://getsas.xyz/api/oauth/revoke
Content-Type: application/x-www-form-urlencoded

وثّق التطبيق بطريقة واحدة: إما HTTP Basic (Authorization: Basic base64(urlencode(client_id):urlencode(client_secret))) أو client_id وclient_secret في جسم الطلب. إذا اختلف client_id في الجسم عن ترويسة Basic يُرفض الطلب بالخطأ invalid_request.

curl --request POST 'https://getsas.xyz/api/oauth/revoke' \
  --user '<CLIENT_ID>:<CLIENT_SECRET>' \
  --data-urlencode 'token=<REFRESH_TOKEN>' \
  --data-urlencode 'token_type_hint=refresh_token'

• كل طلب صالح يُجاب بالرمز 200 وجسم {} حتى لو كان الرمز غير معروف أو ملغى مسبقًا أو تابعًا لتطبيق آخر. لا تعتمد على الاستجابة لمعرفة وجود الرمز.
• إلغاء refresh token يلغي عائلة الرموز كاملة، فتفشل عمليات التجديد اللاحقة.
• بيانات تطبيق غير صحيحة تُجاب بـ 401 والخطأ invalid_client؛ وغياب token أو تجاوزه الحد يُجاب بـ 400 والخطأ invalid_request.
• إذا تلقيت 503 مع temporarily_unavailable فأعد المحاولة لاحقًا مع تأخير متزايد.

تدوير سر العميل

دوّر Client Secret من صفحة بيانات الاعتماد لتطبيقك في لوحة المطور عند الاشتباه في تسربه أو بشكل دوري.

1. دوّر السر وانسخ السر الجديد؛ فهو يظهر مرة واحدة.
2. حدّث كل خادم يستدعي token endpoint أو revocation endpoint بالسر الجديد قبل انتهاء فترة السماح.
3. يبقى السر السابق صالحًا لمدة 24 ساعة كي تستمر الخوادم العاملة أثناء التحديث.
4. بعد انتقال كل الخوادم إلى السر الجديد، أنهِ فترة السماح مبكرًا لإبطال السر السابق فورًا. افعل ذلك مباشرة إذا كان السر القديم قد تسرب.

احفظ السر في backend فقط ولا تسجله في السجلات.

التطبيقات التي لا تملك سر عميل

التطبيقات التي أُنشئت قبل إتاحة أسرار العميل كانت تتبادل الرموز باستخدام PKCE وحده. تعمل هذه التطبيقات الآن ضمن فترة توافق معلنة تظهر في صفحة بيانات الاعتماد، وتُرسل لوحة المطور تنبيهًا لأصحابها. أصدر Client Secret قبل انتهاء الفترة؛ فبعدها يجب أن يُصادَق كل طلب token أو revocation بالسر. يبقى PKCE وredirect URI المطابق حرفيًا مطلوبين في كل الأحوال.

حدود المعدل

لنقطتي token وrevocation حدود معدل لكل عنوان IP ولكل client_id مع عنوان IP. الطلب المرفوض يعيد 429 مع rate_limited وترويسة Retry-After بالثواني؛ انتظر هذه المدة قبل إعادة المحاولة. جدّد الرموز قبل انتهائها وتجنب تجديد التثبيت نفسه من عدة عمليات في الوقت نفسه.

أخطاء شائعة

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

• اختيار النطاقات
• استدعاء API v1
• الاشتراك في Webhooks