أنشئ مفتاح API في لوحة التحكم، واختر النطاقات، واستبدله برمز صالح لمدة 15 دقيقة، واحفظه بأمان وألغِه عند الحاجة، خطوة بخطوة.
مفتاح API هو طريقة دخول برامجك إلى واجهة LinkHarbor API. وهو يتبع مساحة عمل لا شخصًا، ويستطيع بالضبط ما تسمح له به عبر النطاقات. وللاستدعاءات الفعلية تستبدل المفتاح برمز وصول قصير العمر.
من يستطيع إنشاء مفاتيح API؟
- مالكو مساحة العمل ومسؤولوها؛ أما المحرّرون والمشاهدون فلا يرون تحت «Callback وواجهة API» إلا بطاقة «التطبيقات المتصلة»
- ابتداءً من Creator Pro؛ وفي Creator Free تعرض البطاقة «مفاتيح API متاحة ابتداءً من Creator Pro.»
- النشطة في الوقت نفسه: حتى 5 مفاتيح في Creator Pro، وحتى 20 في Creator Agency، وحتى 50 في Enterprise
عند بلوغ الحد يفشل إنشاء المفتاح بالخطأ 409 limit_reached. احذف أولًا مفتاحًا لم تعد تحتاج إليه.
إنشاء مفتاح API
- افتح «Callback وواجهة API» في التنقل
- في بطاقة «مفاتيح API» انقر «+ إنشاء مفتاح جديد»
- تحت «الاسم (اختياري)» أدخل اسمًا تتعرّف به على المفتاح لاحقًا، مثل CI/CD Pipeline أو مزامنة المتجر
- تحت «النطاقات (Scopes)» اختر «قراءة» أو «كتابة» لكل مجال
- انقر «إنشاء المفتاح»
- انسخ «سر المفتاح (خاص)» فورًا واحفظه في مكان آمن
- أغلق النافذة؛ تجد معرّف المفتاح في القائمة في أي وقت
- «الاسم (اختياري)»
- حتى 64 حرفًا. دون اسم يظهر المفتاح في القائمة باسم «مفتاح API #ID».
- «النطاقات (Scopes)»
- مطلوب نطاق واحد على الأقل. «كتابة» يتضمن تلقائيًا «قراءة» للمجال نفسه. الإحصائيات ومدفوعات الداعمين للقراءة فقط، وقوالب مساحة العمل للكتابة فقط. كل النطاقات مشروحة في النطاقات بالتفصيل.
- «سر المفتاح (خاص)»
- يبدأ بـ lt_ ويُعرض مرة واحدة فقط («⚠️ يظهر مرة واحدة فقط — انسخه الآن!»). لا يحفظ LinkHarbor منه إلا قيمة تجزئة (hash)، ولا يستطيع عرضه لك مرة أخرى لاحقًا.
- «معرّف المفتاح:»
- 16 حرفًا من الأرقام والأحرف الكبيرة A–F، مثل 6F668EA6598B0692. وهو ليس سرًا، ويظهر في القائمة مع زر نسخ.
قائمة المفاتيح
يعرض كل مفتاح نشط اسمه والحالة «نشط» ومعرّف المفتاح ونطاقاته و«تاريخ الإنشاء:» و«آخر استخدام:» أو «لم يُستخدم بعد». ويُحدَّث وقت آخر استخدام مع كل استدعاء بالمفتاح، مرة واحدة في الدقيقة على الأكثر. ويعيد «↺ تحديث» تحميل القائمة.
استبدال المفتاح برمز وصول
curl -X POST https://dock.at-harbor.com/v1/token \
-H "Content-Type: application/json" \
-d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'{ "token": "eyJhbGciOiJIUzI1NiIs…", "expires_in": 900 }- token
- رمز الوصول. ترسله مع كل طلب بالشكل Authorization: Bearer <token>.
- expires_in
- مدة الصلاحية بالثواني: 900، أي 15 دقيقة. لا يوجد رمز تحديث (refresh token)؛ فعند انتهاء الصلاحية احصل ببساطة على رمز جديد بمعرّف المفتاح والسر.
يمثّل الرمز مساحة العمل ويحمل نطاقات المفتاح بالضبط. وليس له دور كما للأشخاص: نقاط النهاية التي تخصّصها لوحة التحكم للمالكين والمسؤولين (الأعضاء، والفوترة، وإدارة النطاقات المخصصة، والـ Webhooks، وإعدادات مساحة العمل) تُرفض دائمًا لرموز مفاتيح API. والاستثناءات هي الروابط المختصرة وقوالب مساحة العمل، فهي تعمل بالنطاق المناسب، وكذلك قراءة أسرار Callback (دون السر بنص صريح) بالنطاق read:workspaces.
المحاولات الفاشلة والقفل
| الحالة | الاستجابة |
|---|---|
| معرّف مفتاح أو سر خاطئ، أو مفتاح محذوف | 401 invalid_api_key |
| 5 محاولات فاشلة لمعرّف مفتاح واحد من عنوان IP نفسه | 429 api_key_locked، قفل لمدة 60 ثانية |
| 10 محاولات فاشلة | 429 api_key_locked، قفل لمدة 5 دقائق |
| 20 محاولة فاشلة | 429 api_key_locked، قفل لمدة 30 دقيقة |
| 50 محاولة فاشلة من عنوان IP واحد خلال 10 دقائق | 429 rate_limited، حظر عنوان IP لمدة ساعة واحدة |
مع api_key_locked يكون الوقت المتبقي في details.retry_after_sec. والاستبدال الناجح يعيد العدّاد إلى الصفر.
حذف مفتاح واستبداله
- انقر «حذف» بجوار المفتاح
- اكتب DELETE للتأكيد
- انقر «حذف نهائي»
يتوقف المفتاح عن العمل فورًا، ورموز الوصول التي صدرت سابقًا تتوقف أيضًا من تلك اللحظة وتحصل على 401 invalid_token. لا يوجد زر تدوير. لتبديل المفاتيح، أنشئ مفتاحًا جديدًا، وانقل برنامجك إليه، ثم احذف القديم.
عند تخفيض الخطة
إذا انتقلت مساحة العمل إلى Creator Free، تُلغى كل مفاتيح API. وإذا انتقلت إلى خطة تسمح بمفاتيح أقل، تبقى الأحدث ويُلغى الباقي. والمفاتيح الملغاة لا تعود بعد ترقية لاحقة؛ فتنشئ حينها مفاتيح جديدة. ويتلقى المالكون رسالة بريد إلكتروني بالميزات المعطّلة. المزيد في الإلغاء وتخفيض الخطة وفشل الدفع.
الحفاظ على الأمان
- احفظ السر فقط في مدير أسرار أو في متغيرات البيئة، ولا تضعه أبدًا في الشيفرة المصدرية أو في مستودع Git
- لا تستخدمه أبدًا في شيفرة تعمل في المتصفح أو في تطبيق على جهاز المستخدم
- أنشئ مفتاحًا منفصلًا لكل تطبيق، بأقل عدد ممكن من النطاقات
- احذف المفاتيح التي لم تعد تحتاج إليها فورًا
- إذا اشتبهت في تسرّب: احذف المفتاح وأنشئ مفتاحًا جديدًا
قد يفيدك أيضًا
لم تجد ما تبحث عنه؟
أخبرنا بما تحتاج إليه، وسيساعدك فريق الدعم لدينا شخصيًا.