الترويسة: X-Survanta-Api-Key

ترويسة الطلب X-Survanta-Api-Key

يستخدم كل طلب إلى نقطة نهاية محمية في واجهة برمجة التكامل مخطط المصادقة IntegrationApiKey، ويجب أن يتضمن مفتاح API في ترويسة HTTP الخاصة بـ X-Survanta-Api-Key. هذه هي الطريقة الوحيدة المدعومة لتمرير المفتاح؛ لا تُقبل معاملات سلسلة الاستعلام وحقول جسم الطلب.

تنسيق الترويسة

X-Survanta-Api-Key: <مفتاح-api-الخاص-بك>

استبدل <مفتاح-api-الخاص-بك> بقيمة المفتاح الكاملة التي ظهرت عند إنشاء عميل التكامل أو آخر تدوير له.

مثال: curl

curl -X GET "https://<مضيف-مؤسستك>/api/integrations/reports/surveys" \
     -H "X-Survanta-Api-Key: svt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     -H "Accept: application/json"

مثال: C# HttpClient

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Survanta-Api-Key", apiKey);
client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json"));

var response = await client.GetAsync(
    "https://<مضيف-مؤسستك>/api/integrations/reports/surveys");
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();

مثال: Python requests

import requests

headers = {
    "X-Survanta-Api-Key": "<مفتاح-api-الخاص-بك>",
    "Accept": "application/json",
}
response = requests.get(
    "https://<مضيف-مؤسستك>/api/integrations/reports/surveys",
    headers=headers,
    timeout=30,
)
response.raise_for_status()
data = response.json()

ما لا يجب فعله

كيف يتحقق الخادم من الترويسة؟

عندما يستقبل الخادم طلبا يحتوي على X-Survanta-Api-Key:

1. تُجزَّأ قيمة الترويسة باستخدام الخوارزمية ذاتها المستخدمة عند إنشاء المفتاح.
2. يُبحث عن تجزئة SHA-256 في سجلات TenantApiClient قبل إمكان تطبيق مرشحات استعلام المؤسسة.
3. يجب أن يكون العميل نشطًا وغير ملغى وله تاريخ انتهاء مستقبلي إلزامي. ويجب أيضًا نجاح فحوص المؤسسة والاشتراك وإمكانات الخطة والنطاق وحصة عملاء التكامل.
4. عند النجاح، توضع المؤسسة والنطاقات في الهوية المصادقة، وتُحدّث LastUsedAt، ويكتب سجل تدقيق ApiCall نقطة النهاية وبيانات الطلب الوصفية.
5. يعيد المفتاح المفقود أو الفارغ أو غير الصالح أو غير المعروف HTTP 401 بالاستجابة نفسها:

{
  "errorCode": 401,
  "errorMessage": "Authentication is required. Provide valid credentials or a valid API key.",
  "data": null
}

لا تعاد القيمة الكاملة إلا في نتيجة الإنشاء أو التدوير. يحفظ سجل العميل تجزئة SHA-256 فقط؛ ويجب على المسؤول اعتبار شاشة السر لمرة واحدة فرصة الاسترداد الوحيدة.

حساسية حالة الأحرف

اسم الترويسة X-Survanta-Api-Key يُعامَل بغير حساسية لحالة الأحرف من قِبل معالجة ترويسات ASP.NET Core. أما قيمة المفتاح فهي حساسة لحالة الأحرف — مرّرها كما أُعطيت بالضبط.