المصادقة

تتطلب جميع طلبات واجهة برمجة تطبيقات NueForm المصادقة عبر مفاتيح API. يغطي هذا الدليل كيفية إنشاء المفاتيح واستخدامها في الطلبات والحفاظ على أمانها.

إنشاء مفاتيح API

لإنشاء مفتاح API:

1. سجّل الدخول إلى حسابك في NueForm.
2. انتقل إلى الملف الشخصي وافتح علامة تبويب المطور.
3. انقر على إنشاء مفتاح API.
4. أعطِ مفتاحك اسمًا وصفيًا (مثل "خادم الإنتاج" أو "خط أنابيب CI").
5. انسخ المفتاح فورًا --- سيتم عرضه مرة واحدة فقط.

تنسيق مفتاح API

تتبع مفاتيح API في NueForm تنسيقًا ثابتًا:

nf_<64 hex characters>

يبدأ كل مفتاح بالبادئة nf_ متبوعة بـ 64 حرفًا سداسيًا عشريًا (32 بايت عشوائي). على سبيل المثال:

nf_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

في لوحة التحكم، يتم تعريف المفاتيح ببادئتها (أول 11 حرفًا، مثل nf_a1b2c3d4) حتى تتمكن من التمييز بينها دون كشف القيمة الكاملة.

استخدام مفتاح API الخاص بك

قم بتضمين مفتاح API في ترويسة Authorization لكل طلب باستخدام مخطط Bearer:

Authorization: Bearer nf_your_api_key_here

cURL

curl -X GET https://app.nueform.com/api/v1/forms \
  -H "Authorization: Bearer nf_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json"

JavaScript (fetch)

const NUEFORM_API_KEY = process.env.NUEFORM_API_KEY;

const response = await fetch("https://app.nueform.com/api/v1/forms", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${NUEFORM_API_KEY}`,
    "Content-Type": "application/json",
  },
});

const { data } = await response.json();
console.log(data);

Python (requests)

import os
import requests

api_key = os.environ["NUEFORM_API_KEY"]

response = requests.get(
    "https://app.nueform.com/api/v1/forms",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
)

data = response.json()["data"]
print(data)

أخطاء المصادقة

إذا فشلت المصادقة، تُرجع الواجهة البرمجية استجابة 401 Unauthorized مع رسالة وصفية:

مثال على استجابة الخطأ:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key.",
    "status": 401
  }
}

إدارة المفاتيح

الحدود

يمكن لكل حساب NueForm امتلاك ما يصل إلى 10 مفاتيح API نشطة في أي وقت. إذا كنت بحاجة إلى إنشاء مفتاح جديد وقد وصلت إلى الحد الأقصى، قم بإلغاء مفتاح موجود أولاً.

إلغاء المفاتيح

يمكنك إلغاء مفتاح API في أي وقت من علامة تبويب المطور في ملفك الشخصي. يكون الإلغاء فوريًا --- أي طلب يستخدم مفتاحًا ملغى سيتلقى استجابة 401 Unauthorized.

لإلغاء مفتاح:

1. انتقل إلى الملف الشخصي > المطور.
2. ابحث عن المفتاح الذي تريد إلغاءه (يُعرّف باسمه وبادئته).
3. انقر على إلغاء.
4. أكّد الإجراء.

تتبع آخر استخدام

يتتبع NueForm آخر مرة تم فيها استخدام كل مفتاح API. تحقق من علامة تبويب المطور لمعرفة المفاتيح المستخدمة بنشاط والمفاتيح التي قد يكون من الآمن إلغاؤها.

متطلبات الخطة

الوصول إلى API هو ميزة محدودة تتطلب خطة مدفوعة:

إذا حاولت استخدام مفتاح API على حساب لا تشمل خطته الوصول إلى API، ستتلقى استجابة 403 Forbidden:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API access is not available on your current plan.",
    "status": 403
  }
}

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

اتبع هذه الإرشادات للحفاظ على أمان مفاتيح API الخاصة بك:

لا تحفظ المفاتيح في نظام التحكم بالإصدارات

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

# .env (add .env to your .gitignore)
NUEFORM_API_KEY=nf_your_api_key_here

استخدم متغيرات البيئة

خزّن مفاتيح API في متغيرات البيئة في كل بيئة --- التطوير المحلي والاختبار والإنتاج. لا تقم أبدًا بتضمين المفاتيح مباشرة في الكود المصدري لتطبيقك.

// Good
const apiKey = process.env.NUEFORM_API_KEY;

// Bad --- never do this
const apiKey = "nf_a1b2c3d4...";

استخدم مفاتيح منفصلة لكل بيئة

أنشئ مفاتيح API مختلفة للتطوير والاختبار والإنتاج. هذا يحد من نطاق الضرر إذا تم اختراق مفتاح ويسهّل إلغاء وصول بيئة واحدة.

قم بتدوير المفاتيح بانتظام

أنشئ مفاتيح جديدة بشكل دوري وتخلّص من القديمة تدريجيًا. يسمح NueForm بما يصل إلى 10 مفاتيح نشطة، لذا يمكنك إنشاء مفتاح جديد وتحديث خدماتك والتحقق من أن كل شيء يعمل ثم إلغاء المفتاح القديم.

قصر الاستخدام على جانب الخادم فقط

يجب استخدام مفاتيح API فقط في الكود الذي يعمل على جانب الخادم. لا تكشف أبدًا مفتاح API في JavaScript على جانب العميل أو تطبيقات الهاتف المحمول أو أي كود يعمل في متصفح المستخدم.