الانتقال إلى المحتوى الرئيسي
اسمح للمستخدمين بتسجيل الدخول باستخدام Phaseo وإنفاق أرصدتهم الخاصة في تطبيقك: يمنح OAuth 2.1 مع PKCE خادمك رمز وصول، ويُرفقه وكيل واحد من جهة الخادم بكل استدعاء للـ Gateway. في النهاية يصبح لديك تطبيق محلي فيه تسجيل دخول، ورموز محفوظة في الجلسة تتجدد، واكتشاف للنماذج، وتدفق محادثة عبر /responses، وأداة لاختبار نقاط النهاية الأخرى. تكتشف العينة نقاط نهاية OAuth الخاصة بـ Phaseo، وتتحقق من state وiss عند العودة، وتجدّد الرموز بأمان، وتلغي المفتاح عندما يسجّل المستخدم خروجه. لتجعل وكيل برمجة ينشئ التطبيق نفسه من الصفر، الصق هذه المطالبة:

أنشئ منصة عمل Next.js تتطلب تسجيل الدخول مع OAuth ووكيل Phaseo موحّد.

فتح في Cursor

كيف بُنيت العينة

توجد العينة في examples/oauth-client-nextjs: فصل تسجيل الدخول عن استدعاءات الـ Gateway يعني أن مشكلة في تسجيل الدخول لن تبدو أبدًا كمشكلة في النموذج، وأن جميع نقاط النهاية تشترك في مكان واحد يتعامل مع الرموز.

شغّله

تحتاج إلى Node.js، وتطبيق OAuth يتضمن http://localhost:3000/auth/callback (أو عنوان الاستدعاء الخاص بك) كعنوان إعادة توجيه، وسرّ جلسة عشوائي طويل. أنشئ تطبيق OAuth من الإعدادات → تطبيقات OAuth أو باستخدام OAuth clients API.
1

التثبيت

2

أنشئ .env.local

املأ القيم:تقرأ العينة كل هذه المتغيرات على الخادم فقط. لا تضع أبدًا سرّ العميل أو سرّ الجلسة في متغير يبدأ بـ NEXT_PUBLIC_.تعثر العينة على نقاط نهاية التفويض والرمز والإلغاء وuserinfo من https://api.phaseo.app/.well-known/oauth-authorization-server، وتطلب openid email profile gateway:access. يتيح gateway:access للرمز استدعاء الـ Gateway.
3

شغّل خادم التطوير

افتح http://localhost:3000، وسجّل الدخول، ثم افتح لوحة التحكم.

تحقّق من نجاحه

  • يعود تسجيل الدخول إلى عنوان الاستدعاء الخاص بك وينشئ جلسة.
  • تعرض لوحة التحكم النماذج عبر /api/gateway/models.
  • تحصل جولة محادثة عبر /api/gateway/responses على إجابة، ولا يحمل أي طلب من المتصفح رمز الوصول.
  • يُرفض أي مسار خارج قائمة السماح في الوكيل.

مدد صلاحية الرموز

تعيد نقطة نهاية الرمز رمزين:
  • دوّر الرموز عند كل تجديد. يعيد كل تجديد رمز وصول جديدًا ورمز تجديد جديدًا. احفظ الاثنين وتخلّص من القديمين: يتوقف رمز الوصول القديم عن العمل فورًا، ولا يمكن استخدام رمز التجديد القديم مرة أخرى.
  • جدّد بعد انتهاء الصلاحية. يمكنك التجديد بعد انتهاء صلاحية رمز الوصول، ما دامت صلاحية رمز التجديد لم تنتهِ.
  • لا تُعِد استخدام رمز تجديد أبدًا. استخدامه مرة ثانية يُنهي تسجيل الدخول. يعامله Phaseo كرمز مسرّب ويلغي رمز الوصول وكل رموز التجديد الصادرة من تسجيل الدخول ذاك، فيضطر المستخدم إلى تسجيل الدخول مجددًا.
  • النطاقات تتقلص فقط. لا يضيف التجديد نطاقات أبدًا. يحتفظ بالنطاقات التي وافق عليها المستخدم، مطروحًا منها ما أزاله لاحقًا.
  • عند فشل التجديد. يفشل التجديد بمجرد أن يلغي المستخدم تطبيقك، أو يلغي مفتاحه أو يعطّله، أو يزيل نطاقًا يحتاجه المفتاح (مثل gateway:access)، أو يغادر مساحة العمل. إزالة gateway:access تلغي المفتاح أيضًا، فيتوقف رمز الوصول عن العمل فورًا. ومنح النطاق مجددًا لا يعيد رمز التجديد. أعِد المستخدم إلى تسجيل الدخول.
  • تسجيل الدخول مجددًا يجدّد المفتاح. يجدّد المفتاح نفسه بدلًا من إضافة مفتاح جديد، سواء أرسلت resource=https://api.phaseo.app/v1 أم لا. تحصل على رمز وصول ورمز تجديد جديدين، ويتوقف السابقان عن العمل، ويحتفظ المفتاح بإنفاق هذا الشهر. ويصبح حد الإنفاق الشهري للمفتاح هو الحد الذي وافق عليه المستخدم للتو. أما رمز التجديد من تسجيل دخول سابق فيُرفض فقط، وإرساله إلى نقطة نهاية الرمز أو الإلغاء لا يُنهي تسجيل الدخول الجديد.
  • المفتاح الموقوف مؤقتًا يمنع تسجيل الدخول. إذا كان أي من مفاتيح تطبيقك لذلك المستخدم ومساحة العمل موقوفًا مؤقتًا، أيًّا كان موردُه، تعيد نقطة نهاية الرمز invalid_grant حتى يعيد أحدهم تشغيل المفتاح من الإعدادات → مفاتيح API. لا يعمل التجديد إلا ما دام المفتاح غير ملغى: بعد تسجيل الخروج أو أي إلغاء آخر، يصدر تسجيل الدخول مفتاحًا جديدًا، وتبدأ حدوده وإنفاقه من جديد.
  • سجّل الخروج بالإلغاء. أرسل رمز التجديد إلى https://api.phaseo.app/oauth/revoke. يلغي ذلك المفتاح وكل رموز التجديد الصادرة من تسجيل الدخول، بما فيها رمز أصدره تجديد قبل لحظات.

حدود الإنفاق

في شاشة الموافقة يحدد المستخدم حد إنفاق شهريًا لتطبيقك: $20.00 افتراضيًا، أو مبلغًا آخر، أو بلا حد. بمجرد أن ينفق المفتاح هذا المبلغ خلال شهر تقويمي، تعيد طلبات الـ Gateway الرمز 429 مع key_limit_exceeded حتى الشهر التالي أو حتى يرفع المستخدم الحد من الإعدادات → مفاتيح API. أيًّا كانت النطاقات التي يملكها، لا يستطيع تطبيقك رفع هذا الحد أو الالتفاف عليه عبر API. كل ما يمكنه هو إعادة تسمية مفاتيح API أو حذفها. لا يمكنه إنشاء مفاتيح أو تدويرها، ولا تغيير حدود مفتاح أو حالته أو تاريخ انتهائه، ولا إنشاء مفاتيح إدارة أو أحمال عمل موثوقة، ولا إضافة أعضاء، ولا تغيير الميزانيات أو ضوابط الحماية أو حدود المعدل أو قواعد الإنفاق، ولا تغيير حدود الأسعار في مساحة العمل للتوجيه أو الرجوع من BYOK إلى الأرصدة.

قبل أن تطلقه

  • قلّص قائمة السماح. يسمح lib/gateway.ts بالمسارات التي تستدعيها منصة العمل، إضافةً إلى حالة المهام تحت videos/ وmusic/generate/. احتفظ فقط بالمسارات التي يستدعيها منتجك.
  • شارك عمليات التجديد بين النسخ. يشارك lib/oauth.ts عملية تجديد واحدة بين الطلبات المتوازية في الذاكرة. إذا شغّلت أكثر من نسخة واحدة من الخادم، فانقل ذلك إلى تخزين مشترك، وإلا فقد تجدّد نسختان بالرمز نفسه وتُنهيان تسجيل الدخول.
  • أرسل المحادثة كاملة. لا يخزّن الـ Gateway الردود ويرفض previous_response_id، لذا أعِد إرسال الجولات السابقة في input.
  • استبدل أداة الاختبار. احتفظ بمنصة العمل لضمان الجودة داخليًا، وابنِ تدفقات مخصصة للمستخدمين النهائيين.
لتطبيق يعتمد على مفتاح API دون تسجيل دخول، ابدأ من تطبيق المحادثة على الويب باستخدام Next.js.
آخر تعديل في ١٣ نوفمبر ٢٠٢٦