المصادقة
تستخدم Watch-IP نوعين من المفاتيح حسب نقطة النهاية التي تستدعيها — مفتاح قابل للنشر آمن للمتصفح للاستدعاءات من جانب العميل، ومفتاح سري مخصص للخادم فقط للاستدعاءات من جانب الخلفية (Backend). إرسال النوع الخاطئ يُعيد الرمز 401 أو 403، ولا يُعيد أبدًا استجابة جزئية.
المفاتيح القابلة للنشر (آمنة للمتصفح)
تُستخدم مع GET /v1/geo وPOST /v1/email/validate — وكلاهما مصمَّم للاستدعاء مباشرة من متصفح الزائر. أرسِله كترويسة X-Api-Key (يقبل GET /v1/geo أيضًا معامل استعلام key كبديل احتياطي). إنه ليس سرًّا: فهو يُشحن ضمن JavaScript الخاص بصفحتك، والضابط الفعلي هو قائمة النطاقات المسموح بها (allowed origins) المُهيَّأة للمفتاح، والتي يُتحقق منها مقابل ترويسة Origin/Referer في الطلب. أي طلب من نطاق غير مدرج في تلك القائمة يحصل على 403 دون تعيين أي ترويسة CORS — فالمتصفح يحظر الاستجابة قبل أن يراها الكود الخاص بك على الإطلاق، وهذا هو الإنفاذ الفعلي، لا نص خطأ JSON.
مفتاح قابل للنشر
curl https://api.watch-ip.com/v1/geo \
-H "X-Api-Key: YOUR_PUBLISHABLE_KEY"المفاتيح السرية (للخادم فقط)
تُستخدم مع GET /v1/lookup/{ip} وPOST /v1/lookup وPOST /v1/risk/check — وجميعها نقاط نهاية من خادم إلى خادم دون وجود Origin من متصفح للتحقق منه. أرسِله كـ Authorization: Bearer YOUR_SECRET_KEY من الخلفية (Backend) الخاصة بك فقط؛ لا تُضمِّن أبدًا مفتاحًا سريًا داخل صفحة، أو حزمة تطبيق جوال، أو أي عميل (client) لا تتحكم فيه. استخدام مفتاح قابل للنشر في مسار يتطلب مفتاحًا سريًا، أو مفتاح سري في مسار يتطلب مفتاحًا قابلًا للنشر، يُعيد 403.
مفتاح سري
curl https://api.watch-ip.com/v1/lookup/203.0.113.1 \
-H "Authorization: Bearer YOUR_SECRET_KEY"حد المعدل (Rate Limiting)
يخضع كل مفتاح لحد معدل لكل حساب عميل ضمن نافذة ثابتة مدتها دقيقة واحدة، تُشارَك بين جميع نقاط النهاية التي تستدعيها بدلًا من تتبعها لكل مسار على حدة. تجاوز الحد يُعيد 429 — راجع صفحة الأخطاء وحدود المعدل لمعرفة شكل الاستجابة وكيفية التراجع (backoff). يحتسب حد المعدل في الدقيقة استدعاءات HTTP لا العناصر: الدفعة التي تضم حتى 100 عنوان IP أو بريد إلكتروني تُحتسب طلبًا واحدًا، بينما يظل كل عنصر يُحتسب على حدة ضمن الحد الشهري للطلبات.
النطاقات المخصصة
تتضمن خطتا Growth وScale مسار إعداد نطاق مخصص في لوحة التحكم، بحيث يمكن توجيه الطلبات إلى اسم مضيف على نطاقك الخاص بدلًا من api.watch-ip.com. تتوقف الإتاحة على أهلية الحساب ونجاح إعداد DNS/SSL — وجِّه تكاملك إلى عنوان URL الأساسي الذي تؤكد لوحة التحكم أنه نشط.