OAuth2

مصادقة OAuth2

اسمح لحسابات Sofia الأخرى بربط تطبيقك: سجّل عميلًا، ونفّذ تدفق authorization code مع PKCE، وجدّد الرموز، واطلب الصلاحيات (scopes) المناسبة.

OAuth: رمز التفويض مع PKCE

سجّل عميلًا في الإعدادات › API › عملاء التطبيقات: اسمه وشعاره وسياسة الخصوصية والصلاحيات التي يجوز له طلبها وعناوين إعادة التوجيه عبر https. للعميل السري (confidential) سرّ خاص، أما العميل العام (public) (تطبيق جوال، إضافة متصفح) فلا سرّ له ويعتمد على PKCE وحده.

وجّه الشخص إلى نقطة نهاية التفويض مع تحدّي PKCE (إلزامي بصيغة S256) وstate تحتفظ به في جلسته:

javascript

import { createHash, randomBytes } from 'node:crypto';

const verifier = randomBytes(32).toString('base64url');
const challenge = createHash('sha256').update(verifier).digest('base64url');
const state = randomBytes(16).toString('base64url');

const url = new URL('https://api.sofia-post.com/api/v1/oauth/authorize');
url.search = new URLSearchParams({
  response_type: 'code',
  client_id: process.env.SOFIA_CLIENT_ID,
  redirect_uri: 'https://app.example.com/oauth/callback',
  scope: 'establishments:read posts:read posts:write offline_access',
  state,
  code_challenge: challenge,
  code_challenge_method: 'S256',
}).toString();

يسجّل الشخص الدخول إلى Sofia، ويرى اسمك وشعارك وصلاحياتك، ويختار مساحة عمل ويوافق. ثم تعيده Sofia إلى عنوان إعادة التوجيه الخاص بك مع code وstate والمُصدِر iss. تحقق من الاثنين، ثم بدّل الرمز:

bash

curl -X POST https://api.sofia-post.com/api/v1/oauth/token \
  -u "$SOFIA_CLIENT_ID:$SOFIA_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=$CODE \
  -d redirect_uri=https://app.example.com/oauth/callback \
  -d code_verifier=$VERIFIER

json

{
  "access_token": "sofia_live_at_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "establishments:read posts:read posts:write offline_access",
  "refresh_token": "sofia_live_rt_…"
}

الرمز صالح 5 دقائق ولمرة واحدة. إذا أُعيد استخدامه رُفض وتوقفت الرموز التي منحها.
يدوم رمز الوصول ساعة واحدة ويتصرف على مساحة العمل التي اختارها الشخص فقط.
لا يُعاد refresh_token إلا إذا طلبت offline_access. وهو للاستخدام مرة واحدة: احتفظ بالجديد في كل مرة. إعادة استخدام رمز تحديث مستخدَم تُلغي التفويض كله.

bash

curl -X POST https://api.sofia-post.com/api/v1/oauth/token \
  -u "$SOFIA_CLIENT_ID:$SOFIA_CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token=$REFRESH_TOKEN

OAuth: بيانات اعتماد العميل

يستطيع العميل السري أيضًا أن يتصرف على مساحة عمل يملكها صاحبه، دون شخص في الحلقة. عندما يملك العميل عدة مساحات عمل، سمِّ إحداها بـ workspace_id.

bash

curl -X POST https://api.sofia-post.com/api/v1/oauth/token \
  -u "$SOFIA_CLIENT_ID:$SOFIA_CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d workspace_id=$WORKSPACE_ID

الصلاحيات (scopes)

النطاق	يتيح
`establishments:read`	عرض المنشآت
`accounts:read`, `accounts:write`	قراءة الشبكات المتصلة؛ إنشاء روابط الربط
`media:read`, `media:write`	قراءة مكتبة الوسائط؛ رفع الوسائط واستيرادها
`posts:read`, `posts:write`	عرض المنشورات ومتابعتها؛ نشرها وتعديلها وحذفها
`insights:read`	قراءة الإحصاءات
`webhooks:read`, `webhooks:write`	عرض webhooks؛ تسجيلها واختبارها وحذفها
`offline_access`	OAuth فقط: استلام رمز تحديث

الاستدعاء الذي يفتقر إلى النطاق المطلوب يُجاب بـ 403 insufficient_scope. تسرد بيانات الخادم الوصفية (RFC 8414) كل نقطة نهاية وكل نطاق:

text

https://api.sofia-post.com/.well-known/oauth-authorization-server/api/v1/oauth