مرجع API
صادق على Tungsto API الحالي
افهم عقد ملفات تعريف الارتباط للجلسة ورمز CSRF المدعوم قبل التكامل مع نقاط نهاية الحساب والفوترة والخوادم.
في هذه الصفحة
قبل أن تبدأ
- حساب موجود وإمكانية الوصول إلى خدمة الحساب الجارية عبر HTTPS.
- عميل يحافظ على ملفات تعريف ارتباط الجلسة بين الطلبات.
- للتغييرات، رمز CSRF المرتبط بنفس الجلسة النشطة.
استخدم طريقة المصادقة المدعومة
مسارات API المحمية تستخدم جلسة الحساب المنشأة عند تسجيل الدخول. ملف تعريف الارتباط للجلسة يُسمى __Host-tungsto-session ومُعلَّم بـ Secure و HttpOnly. ملف تعريف ارتباط ثانٍ، __Host-tungsto-csrf، يدعم التحقق من الطلبات. تغييرات الحساب تتطلب ترويسة x-csrf-token مطابقة لتلك الجلسة، بالإضافة إلى ملف تعريف ارتباط الجلسة.
شاشة مفاتيح SSH و API تنشئ وتسرد وتلغي المفاتيح المحددة النطاق. أرسل Authorization: Bearer متبوعًا بالمفتاح لمرة واحدة. يسمح نطاق القراءة بـ GET /api/v1/servers وتفاصيل الخادم و /api/v1/orders. يسمح نطاق الخوادم بالخوادم وتفاصيل الخادم و /api/v1/network. يسمح نطاق الفوترة بـ GET /api/v1/ledger.. يتم رفض جميع تغييرات مفاتيح API حتى لو كانت جلسة المتصفح موجودة أيضًا. تغيير كلمة المرور أو استرداد الحساب يلغي المفاتيح الحالية. لا تبني أتمتة أجهزة إنتاج أو دفع غير مراقبة حول هذه المعاينة المحلية.
أنشئ جلسة وتحقق منها
الطلب أعلاه يعرض أسماء الحقول فقط. قدّم بيانات الاعتماد بشكل آمن في عميلك الخاص؛ لا تحفظ كلمة مرور حقيقية في أمثلة مشتركة أو مخرجات تشخيصية. الطلبات من المتصفح يجب أن تبقى على نفس الموقع. ترويسة Origin التي تسمي أصلًا آخر تُرفض.
- أرسل طلب POST بتنسيق JSON إلى /api/v1/auth/login يتضمن اسم المستخدم وكلمة المرور. احتفظ بقيم Set-Cookie التي يعيدها الرد الناجح في مخزن ملفات تعريف الارتباط المحمي لدى العميل.
- احتفظ بـ csrfToken المُعاد في استجابة JSON مع تلك الجلسة. لا تخلط رمزًا من تسجيل دخول مع ملفات تعريف ارتباط من آخر.
- اتصل بـ GET /api/v1/me مع ملفات تعريف الارتباط للتحقق من الحساب. تحتوي استجابته على اسم المستخدم وbalanceUsd وcsrfToken.
- لتغيير محمي، أرسل ملفات تعريف ارتباط الجلسة وContent-Type: application/json وx-csrf-token. أدرج Idempotency-Key عندما تتطلب النهاية ذلك.
- أنهِ الجلسة باستخدام POST /api/v1/auth/logout عندما ينتهي العميل.
POST /api/v1/auth/login HTTP/1.1
Content-Type: application/json
{"username":"your-username","password":"your-password"}تعامل مع انتهاء الجلسة وأخطاء التحقق
يغير استرداد الحساب الناجح كلمة المرور ويلغي الجلسات الحالية ويصدر رمز استرداد بديل. يجب على العملاء الذين يستخدمون ملفات تعريف ارتباط سابقة المصادقة مرة أخرى. تنتهي الخدمة أيضًا الجلسات، لذا فإن الاتصال الناجح السابق ليس اعتمادًا غير محدود.
| الاستجابة | المعنى | الإجراء التالي |
|---|---|---|
| 401 authentication_required | لم يتم العثور على جلسة حساب صالحة. | سجّل الدخول مرة أخرى واحتفظ بملفات تعريف الارتباط الجديدة. |
| 401 session_invalid | لا تتحقق الجلسة وملف تعريف الارتباط CSRF معًا. | ابدأ تسجيل دخول جديدًا بدلاً من إعادة استخدام ملفات تعريف ارتباط مختلطة. |
| 403 csrf_failed | طلب التغيير يفتقر إلى رمز التحقق المطابق. | أعد تحميل معلومات الجلسة واستخدم رمزها الحالي. |
| 403 origin_rejected | الأصل المقدم مختلف عن أصل الطلب. | نفّذ الطلب من سياق الموقع نفسه المدعوم. |
| 429 rate_limited | تم إجراء محاولات مصادقة كثيرة جدًا. | انتظر قبل المحاولة مرة أخرى؛ لا تعاود المحاولة باستمرار. |
حافظ على التكامل ضمن العقد الحالي
تعرض شاشة الأمان الجلسات النشطة من خلال GET /api/v1/sessions وتلغي جلسة مملوكة من خلال DELETE /api/v1/sessions/:id.. تعرض شاشة المفاتيح وتلغي مفاتيح API. لا يوجد تدفق OAuth. التسجيل والاسترداد هما عمليتان تفاعليتان للوصول إلى الحساب، وليستا بديلاً عن آلية حساب خدمة. تجنب توزيع ملفات تعريف ارتباط جلسة شخص واحد بين أدوات أو مستخدمين متعددين.
استلام نجاح المصادقة يؤكد الوصول إلى الحساب، وليس أن كل عملية خارجية متاحة. تسوية العملات المشفرة تحتاج إلى مزود متصل؛ إجراءات الخادم الفعلية تحتاج إلى تنفيذ المشغل للطلبات المصفوفة. اقرأ دليل العمليات لنتائج نقطة النهاية المحددة وسلوك إعادة المحاولة قبل تفسير استجابة ناجحة كإجراء مكتمل في العالم الحقيقي.