يعمل مفتاح API مثل كلمة مرور لبرنامج. وهو أيضًا صلاحية إنفاق: من يملكه يستطيع استخدام رصيدك.
كيف يعمل
تتعامل واجهات LLM API مع المفتاح بوصفه رمز Bearer. يرسله العميل مع كل طلب:
curl https://inference.broadnet.ai/v1/models \
-H "Authorization: Bearer $BROADNET_API_KEY"
يعرّف RFC 6750 رمز Bearer بأنه رمز يستطيع “any party in possession of the token” (ترجمة: أي طرف يحوز الرمز) استخدامه. لا يوجد عامل تحقق ثانٍ. ولهذا يقول الـ RFC نفسه إن على العملاء إرسال رموز Bearer دائمًا عبر TLS (https://).
يبحث المزوّد عن المفتاح، ويحدّد الحساب، ويتحقق من الحدود والسياسات، ثم يخدم الطلب أو يرفضه. والمفتاح المفقود أو الخاطئ يُرجع غالبًا 401؛ أما المفتاح الذي ترفضه سياسة ما، مثل قائمة عناوين IP المسموح بها، فيُرجع غالبًا 403.
لماذا يهم
المفتاح المسرَّب من أكثر الطرق شيوعًا لخروج فاتورة API عن السيطرة، لأن الروبوتات تمسح الشيفرة العامة بحثًا عن الأسرار. وقد يكشف أيضًا بيانات إذا وصل المفتاح إلى نقاط نهاية تُرجع تفاصيل الحساب. الممارسات الجيدة، بما يتوافق مع إرشادات OWASP للأسرار:
- حمّل المفاتيح من متغيرات البيئة أو من مدير أسرار. لا تضعها أبدًا في commit ولا تدمجها في صور الحاويات.
- امنح كل تطبيق أو وكيل مفتاحه الخاص، لتتمكن من إلغاء أحدها دون إيقاف كل شيء.
- بدّل المفاتيح وفق جدول زمني، وفورًا بعد أي تسرّب مشتبه به.
- قيّد الأماكن التي يعمل منها المفتاح، مثلًا بقائمة مسموح بها لعناوين IP الخوادم.
في BroadNet Inference
تفصل BroadNet بين نوعين من بيانات الاعتماد. مفتاح الاستدلال يستدعي النماذج على /v1/*. وبيانات اعتماد البوابة (portal credential) تؤتمت إدارة الحساب: المفاتيح وعناوين IP المسموح بها والمشتريات. تعامل مع الثانية على أنها صلاحية كاملة على الحساب.
يُعرض كلاهما مرة واحدة فقط. لا تحتفظ BroadNet إلا ببصمة SHA-256، لذا لا تستطيع عرض المفتاح مرة أخرى. يصلح مفتاح الدفع حسب الاستخدام سنة واحدة، ويمكن أن يضم الحساب حتى عشرة مفاتيح نشطة. ويمكن أن يحمل كل مفتاح قائمته الخاصة من عناوين IP المسموح بها. وبعد الإلغاء أو تغيير القائمة، تتوقف الطلبات الجديدة خلال خمس ثوانٍ.
مفاتيح الخطط ثابتة السعر منفصلة ولا تُخصم أبدًا من رصيدك. وتجد خطوات الإعداد في مفاتيح API وقوائم عناوين IP المسموح بها، ورموز الحالة في الأخطاء وإعادة المحاولة.
أخطاء شائعة
- تسجيل ترويسات الطلب كاملة. هذا يكتب المفتاح في سجلاتك.
- مشاركة مفتاح واحد بين أفراد الفريق. تفقد بذلك القدرة على إلغاء وصول شخص بعينه.
- إرسال المفتاح إلى الدعم. أرسل قيمة الترويسة
X-Request-IDبدلًا منه.