OAuth 2.0: بيانات اعتماد العميل (Client Credentials)

نظرة عامة

صُمّم منح Client Credentials للتكاملات بين الخوادم حيث لا يوجد مستخدم حاضر: خطوط CI، والمهام المجدولة، وخدمات الواجهة الخلفية، وتكاملات منصّات SaaS. إذ يبادل تطبيقك زوج client_id / client_secret برمز وصول Bearer قصير الأجل.

متى تستخدم OAuth ومتى مفاتيح API

1. إنشاء عميل OAuth

انتقل إلى Studio ← واجهة المطوّرين ← عملاء OAuth 2.0 واضغط إنشاء عميل OAuth. امنح العميل اسمًا واضحًا، وضيّق النطاقات إن أردت.

2. الحصول على رمز وصول

أرسل طلب POST إلى نقطة نهاية الرمز بصيغة application/x-www-form-urlencoded (المعيار في RFC) أو application/json (للتيسير):

curl -X POST https://pollslive.com/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=plv_cid_…&client_secret=plv_cs_…&scope=polls:read polls:write"

curl -X POST https://pollslive.com/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "plv_cid_…",
    "client_secret": "plv_cs_…",
    "scope": "polls:read polls:write"
  }'

{
  "access_token": "plv_oauth_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "polls:read polls:write"
}

تتبع الأخطاء صيغة RFC 6749 §5.2. { "error": "invalid_client", "error_description": "…" }

3. استخدام الرمز

ضمّن access_token كرمز Bearer في كل طلب إلى API، تمامًا كما تفعل بمفتاح API:

curl https://pollslive.com/api/v1/polls \
  -H "Authorization: Bearer plv_oauth_…"

ينبغي لتطبيقك تخزين الرمز مؤقتًا وطلب رمز جديد فقط عند اقتراب expires_in (مثلًا عند تبقّي أقل من خمس دقائق).

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

تصلح الرموز لمدة ساعة واحدة (expires_in: 3600). ولا يوجد رمز تحديث. اطلب ببساطة رمزًا جديدًا ببيانات اعتماد العميل عند انتهاء الحالي. ولأن التدفّق يجري في جهة الخادم، لا يغادر سرّ العميل واجهتك الخلفية أبدًا.

let token = null;
let expiresAt = 0;

async function getToken() {
  if (token && Date.now() < expiresAt - 5 * 60 * 1000) return token;

  const res = await fetch("https://pollslive.com/api/oauth/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      grant_type: "client_credentials",
      client_id: process.env.OAUTH_CLIENT_ID,
      client_secret: process.env.OAUTH_CLIENT_SECRET,
    }),
  });
  const data = await res.json();
  token = data.access_token;
  expiresAt = Date.now() + data.expires_in * 1000;
  return token;
}

النطاقات

تتيح لك النطاقات تحديد ما يمكن لعميل OAuth فعله. وإن لم تحدّد أي نطاق عند إنشاء العميل، فإنه يرث وصولًا كاملًا إلى مساحة العمل (بما يعادل مفتاح API).

راجع مرجع النطاقات الكامل للاطلاع على القائمة كلها.

إبطال عميل

يؤدي إبطال العميل إلى إلغاء جميع الرموز الصادرة له فورًا. وستفشل الطلبات الجارية التي تستخدم أحد هذه الرموز بالخطأ 401 invalid_oauth_token.

انتقل إلى Studio ← واجهة المطوّرين ← عملاء OAuth 2.0 واضغط إبطال.