الرابط الأساسي https://api.echonova.ai

المطورون

أفضل الممارسات للأمان

كيف تمنع تسرّب مفتاح API، وتحدّ مما يستطيع المفتاح المتسرّب فعله، وتستبدل المفتاح بأمان، ولا تثق إلا بـ Webhooks الحقيقية، وتدقّق ما فعلته مفاتيحك.

مفتاح API رمز حامل (Bearer): من يحمله يستطيع إنفاق رصيد مساحة عملك حتى تعطّله أو تحذفه، ولا تستطيع الواجهة أن تميّز خادمك عن مهاجم نسخ المفتاح. الضوابط التالية موجودة كي يصعب تسريب المفتاح، ويكون الضرر قليلًا إن تسرّب، ويسهل استبداله. والمنطق نفسه ينطبق على Webhook، وهو نقطة نهاية يستطيع أي أحد أن يرسل إليها بعد أن يعرف عنوانها.

احفظ المفتاح حيث لا يقرؤه إلا خادمك

تفحص الواجهة header Authorization وحده، ولا شيء غيره: لا الأصل (origin)، ولا عنوان IP، ولا شهادة عميل. ويستطيع أي أحد استخراج المفتاح واستخدامه من أي مكان إذا وصل إلى حزمة متصفح، أو تطبيق موبايل، أو بناء سطح مكتب، أو مستودع عام. احتفظ به على خادم تتحكم فيه، واقرأه من متغير بيئة أو من مدير أسرار عند بدء التشغيل، ودع الخادم يستدعي الواجهة نيابةً عن عملائك. لا يمكن استرجاع السر بعد إنشائه، لا منك ولا من غيرك: تعرضه البوابة مرة واحدة، وبعدها تعرض أول 8 محارف فقط.

الموصى به

  • مسار خلفي خاص بك يستدعيه تطبيقك، ويحمل المفتاح ويستدعي الواجهة.

الأقل فاعلية

  • المفتاح في إعدادات تطبيق موبايل، ويستدعي التطبيق الواجهة مباشرة من الجهاز.

امنح كل نظام مفتاحه الخاص، وبالوصول الذي يحتاجه فقط

تتيح لك البوابة تشكيل المفتاح عند إنشائه، أو عند تعديله:

الضابط ما يحدّه ما يحدث خارج الحد
الخدمات أي من تحويل النص إلى كلام وتحويل الكلام إلى نص يستطيع المفتاح استدعاءها. امنح وصول للخدمات التي يحتاجها النظام، واترك الباقي على بدون وصول. 403 مع This API key does not have access to Text-to-Speech services، أو المكافئ لتحويل الكلام إلى نص.
حد الرصيد كم رصيدًا يستطيع المفتاح إنفاقه في كل دورة فوترة. تُرفض استدعاءات تحويل النص إلى كلام بالرمز 429 مع Monthly spending limit exhausted قبل أن تعمل. وتعمل استدعاءات تحويل الكلام إلى نص وتُحسب بعد ذلك.
مفتاح مُفعَّل في صف المفتاح هل يُقبل المفتاح أصلًا. 401 في كل طلب حتى تفعّله من جديد.

أنشئ مفتاحًا لكل نظام يستدعي الواجهة، وسمّه باسم ذلك النظام. فإذا تسرّب مفتاح، تعطّل ذلك المفتاح وحده، ويواصل الآخرون العمل. وعندما يُظهر سجل الطلبات استدعاءً لا تتعرف عليه، يخبرك اسم المفتاح أي نظام صنعه. لا تحفظ البوابة مفتاحًا دون خدمة واحدة على الأقل، فامنح النظام ما يحتاجه بالضبط. والمفتاح الذي أُنشئ قبل هذا التغيير دون اختيار أي خدمة ما زال يستطيع استدعاء كل الخدمات، لذلك افتحه واختر خدماته.

اصنع حدًا للضرر بحد الرصيد

حد الرصيد هو الضابط الوحيد الذي يحدّ الإنفاق على مفتاح قبل أن تلاحظ المشكلة. اضبطه على كل مفتاح يعمل دون إشراف، عند مستوى أعلى قليلًا من الاستخدام الشهري المعتاد للنظام. ثم اشترك في Webhook للحدثين الخاصين بالإنفاق: spending.warning عند 80% من الحد، وspending.exhausted عند الحد نفسه، حتى يصلك أي ارتفاع غير متوقع كرسالة بدلًا من أن يصلك كفاتورة. يحمل الحدثان معرّف المفتاح، وأحداث Webhook تحتوي على الأجسام. يُعاد ضبط العداد عند أول استدعاء يُحتسب عليه رصيد في دورة فوترة جديدة؛ راجع الرصيد للحساب.

استبدل المفتاح بدلًا من أن تأمل أنه ما زال سرًا

سر المفتاح ثابت منذ إنشائه. ولاستبداله، أنشئ مفتاحًا جديدًا، وانشره، ثم احذف القديم:

الخطوة ما تفعله
إنشاء أنشئ مفتاحًا جديدًا بالخدمات نفسها وحد الرصيد نفسه. انسخ السر أو نزّله؛ يُعرض مرة واحدة.
نشر ضع السر الجديد في إعدادات خادمك، وأعد التشغيل أو التحميل حتى يُستخدم.
تحقّق أرسل طلبًا واحدًا بالمفتاح الجديد، وتأكد من 200. يتوقف تاريخ آخر استخدام للمفتاح القديم عن التحرك عندما لا يستخدمه أحد.
حذف حذف المفتاح القديم. الحذف لا يُلغى، وأي طلب به يحصل على 401 من تلك اللحظة.

افعل هذا وفق جدول تستطيع التزام به، وفورًا عندما يغادر شخص كان يعرف السر، أو عندما يُخرَج جهاز كان يحمله من الخدمة. وإذا لم تكن متأكدًا من تسرّب مفتاح، فعطّله أولًا بمفتاح مُفعَّل في صف المفتاح، فهذا قابل للعكس، ثم قرر بشأن الحذف لاحقًا. ويحتفظ سجل الطلبات بسجلات المفتاح المحذوف، فلا يضيع شيء للتدقيق.

لا تثق بـ Webhook إلا بعد أن تتحقق منه

نقطة نهاية Webhook لديك عامة. يستطيع أي أحد يعرف عنوانها أن يرسل جسم JSON يشبه job.completed مع audioUrl يختاره، أو spending.exhausted يجعلك تعطّل مفتاحًا. توقّع EchoNova كل تسليم بسر توقيع Webhook على الطابع الزمني والجسم، فيفشل أي طلب مزوّر أو معدّل في الفحص. تحقق قبل أن تتصرف، وقارن في زمن ثابت، وارفض طابعًا زمنيًا بعيدًا عن ساعتك؛ الخطوات في التحقق من توقيع Webhook.

المعلومة لماذا تهم
يُعاد سر التوقيع مرة واحدة، عند الإنشاء. احفظه بالعناية نفسها التي تحفظ بها مفتاح API. وللحصول على سر جديد، أنشئ Webhook ثانيًا واحذف الأول، كما في صفحة التحقق.
تقبل البوابة عناوين نقاط نهاية https فقط. احتفظ بشهادة TLS صالحة على نقطة النهاية. يعبر الجسم وكل header، بما فيها التوقيع، الشبكة مشفّرًا دائمًا.
تحمل إعادة المحاولة طابعًا زمنيًا وتوقيعًا جديدين، لكن الجسم نفسه. أزِل التكرار بناءً على المحتوى، لا على التوقيع.
لا تأتي عمليات التسليم من مجموعة ثابتة ومنشورة من عناوين IP. لا تعتمد على قائمة سماح بعناوين IP للتحقق من الأصالة؛ اعتمد على التوقيع.
لا يهم إلا رمز الحالة في استجابتك. أجب بـ 2xx مرة واحدة عند نجاح التحقق من التوقيع، ثم عالج البيانات بعد ذلك.

دقّق ما فعلته مفاتيحك

كل طلب يعثر فيه إيكونوڤا على مفتاح API يُسجَّل مع طريقته ومساره ورمز حالته ومفتاحه ووقته، وتعرض البوابة أحدث هذه السجلات في تبويب سجل الطلبات. استخدمه للإجابة عن سؤال "هل فعل نظامنا هذا الاستدعاء؟"، ولرصد مفتاح يُستخدم من نظام لا ينبغي أن يملكه. يُسجَّل 403 وأول 429 خاص بالمفتاح في كل نافذة للحد، أما 401 و429 لكل عنوان IP و429 الخاص بالمفتاح الذي يلي الأول في النافذة نفسها فلا تُسجَّل. ولا يحتوي السجل على جسم طلب أو استجابة أو أي header، ويُقرأ في البوابة فقط. واحتفظ بسجلك الخاص لكل طلب يرسله خادمك، مع اسم المفتاح وjobId الذي استلمه، حتى يمكن مطابقة السجلين. وتشرح صفحة اقرأ سجل الطلبات كل عمود.

يستطيع مالك مساحة العمل أن ينشئ المفاتيح و Webhooks ويعدّلها ويحذفها، وأن يقرأ السجل. ومن يستطيع إنشاء مفتاح يستطيع إنفاق رصيدك، فاحمِ تسجيل دخول المالك بالمصادقة الثنائية.

الأسئلة الشائعة

تسرّب مفتاح. ماذا أفعل أولًا؟

عطّله بمفتاح مُفعَّل في صف المفتاح، تحت المطورون، ثم مفاتيح واجهة برمجة التطبيقات. يحصل الطلب التالي به على 401. ثم أنشئ بديلًا، وانشره، واحذف المفتاح القديم.

هل يمكنني تقييد المفتاح بعنوان IP خادمي؟

لا. تفحص الواجهة header Authorization وحده. احتفظ بالمفتاح على خادمك، وضع عليه حد رصيد.

هل أستطيع استرجاع السر إذا فقدته؟

لا. أنشئ مفتاحًا جديدًا، واحذف القديم.

هل يمكنني تدوير سر Webhook في مكانه؟

لا. أنشئ Webhook ثانيًا للعنوان نفسه والأحداث نفسها، وانشر سره، ثم احذف الأول. يجب أن تقبل نقطة نهايتك السرّين معًا خلال فترة التداخل.

من في مساحة عملي يستطيع إنشاء المفاتيح؟

مالك مساحة العمل، الذي يحمل دوره الصلاحية developer_api.manage. والمفتاح ينفق رصيدك، فاحرص على أمان حساب المالك.