تشرح هذه المقالة كيفية إنشاء مفتاح API محدود النطاق لتكامل ما، وكيفية الحفاظ على أمانه. الوصول إلى API وWebhooks متضمن بدءًا من خطة Growth. لا يمكن إنشاء المفاتيح أو تغييرها أو إلغاؤها إلا لمسؤولي الحساب.
¶ نوعان من بيانات الاعتماد
- رمز الوصول الشخصي. تجده في إعدادات ملفك الشخصي. يعمل بصفتك أنت وبكامل صلاحيات دورك، ولا تنتهي صلاحيته أبدًا. استخدمه لاستكشاف API، لا لتكاملات الإنتاج.
- مفتاح API محدود النطاق. ينشئه مسؤول لتكامل واحد. يبدأ بـ
hc_، ويعمل بصفة الحساب، ولا يحمل سوى النطاقات التي تمنحها، إضافةً إلى حد معدل خاص به، وقائمة عناوين IP مسموح بها اختيارية، وتاريخ انتهاء اختياري.
يُرسل كلاهما في الترويسة نفسها: Authorization: Bearer <token>.
¶ إنشاء مفتاح في HueChat
- سجّل الدخول بصفتك مسؤولًا أو مالك الحساب. افتح القائمة أسفل اسمك في أعلى اليمين، واختر الملف الشخصي، ثم تبويب Developer API (واجهة API للمطورين).
- راجع بطاقات السعة: الوصول إلى API، واستيراد السجل التاريخي، وطلبات الحساب في الدقيقة، وحد الذروة خلال 10 ثوانٍ، والمفاتيح النشطة (حتى 10)، والاستخدام الشهري. ويحدد HueChat الحدود القصوى للخطة.
- اختر Create API key (إنشاء مفتاح API) وأعطه اسمًا يوضح الغرض منه، مثل "مزامنة CRM".
- اختر النطاقات التي يحتاجها التكامل ولا شيء أكثر. لا تحتاج المزامنة للقراءة فقط سوى
contacts:readوconversations:readوmessages:read. - اختياري: حدد حد معدل بعدد الطلبات في الدقيقة (من 1 إلى 100,000؛ القيمة الافتراضية 1,000).
- اختياري: أضف عناوين IP أو نطاقات CIDR الخاصة بخوادمك إلى قائمة المسموح بها. تُرفض الطلبات القادمة من أي عنوان آخر.
- اختياري: حدد تاريخ انتهاء. تتوقف المفاتيح المنتهية عن العمل تلقائيًا.
- احفظ، ثم انسخ المفتاح الكامل فورًا. يعرضه HueChat مرة واحدة فقط ("Copy this secret now. HueChat will not show it again"). وبعدها لا يعرض سوى البادئة.
الملف الشخصي، تبويب Developer API: بطاقات السعة ومفاتيح API محدودة النطاق
إذا كنت تفضل البرمجة النصية، يمكن إنشاء المفتاح نفسه عبر POST /api/v2/accounts/{account_id}/api-keys باستخدام رمزك الشخصي. الطلب الكامل وجدول النطاقات الكامل متاحان في مركز المطورين على https://developers.huechat.ai.
¶ النطاقات
تأتي النطاقات في أزواج قراءة وكتابة للمحادثات والرسائل وجهات الاتصال وصناديق الوارد والفرق ووكلاء الذكاء الاصطناعي والبث الجماعي وWebhooks والتصنيفات والأتمتة، إضافةً إلى reports:read وaccount:read. يعرض المنتقي كل نطاق يمكن لحسابك منحه، بما في ذلك النطاقات الأحدث للقوالب وسير العمل والتذاكر والصفقات والعملاء المحتملين والنماذج والمواعيد (appointments:read وappointments:write وappointments:settings وappointments:history:write لاستيراد المواعيد السابقة). يتلقى المفتاح الذي يفتقر إلى نطاق ما ردًا 403 مع الرسالة "API key scope is not authorized for this route".
¶ إدارة المفاتيح لاحقًا
من صفحة Developer API نفسها (أو استدعاءات API المقابلة)، تتوفر لكل مفتاح الخيارات الاستخدام وتعديل وRotate (تبديل) وRevoke (إلغاء)، ومن خلالها يمكنك:
- تحديث النطاقات أو حد المعدل أو قائمة عناوين IP المسموح بها أو تاريخ الانتهاء.
- تبديل المفتاح. تحصل على سر جديد لمعرّف المفتاح نفسه، فتستبدله في تكاملك دون المساس بالنطاقات.
- إلغاء المفتاح. يتوقف عن العمل فورًا.
- عرض الاستخدام لمعرفة متى ومن أين استُخدم المفتاح.
يُسجل كل إنشاء وتغيير وتبديل وإلغاء في سجل تدقيق مفاتيح API.
¶ الحفاظ على أمان المفتاح
خزّن المفاتيح في متغير بيئة أو مدير أسرار، وليس في كود المتصفح أو مستودع عام أبدًا. استخدم مفتاحًا واحدًا لكل تكامل لتتمكن من إلغاء شيء واحد بالضبط عند الاستغناء عن شريك. إذا تسرب مفتاح، فبدّله أو ألغه فورًا. تُخزن المفاتيح كتجزئات (hashes) فقط، لذا لا يستطيع HueChat أن يعرض لك مفتاحًا مفقودًا.