البدء السريع لواجهة API

أنشئ حساب خدمة ومفتاح API في Developer Hub، ثم أرسل أول طلب لك. يستخدم هذا الدليل السريع المصادقة بمفتاح API، ولا تحتاج إلى عميل OAuth. راجع المصادقة إذا كان تكاملك يتطلب رموز وصول OAuth قصيرة الأمد.

المتطلبات الأساسية

صلاحية مسؤول للوصول إلى لوحة التحكم في Living Security.
أن يكون Developer Hub ظاهرًا ضمن الإعدادات ← التكاملات والمطورون ← Developer Hub.

إنشاء بيانات الاعتماد

إنشاء حساب خدمة

في Developer Hub، افتح علامة التبويب حسابات الخدمة وأنشئ حسابًا. امنحه اسمًا وصفيًا (على سبيل المثال reporting-pipeline) ثم امنحه الأذونات التي يمكن لمفاتيحه استخدامها — ويكفي لهذا الدليل الإذن organization:read.تمثل أذونات الحساب الحد الأقصى لكل مفتاح يُنشأ ضمنه: فلا يمكن لأي مفتاح أن يفعل أكثر مما يسمح به حساب الخدمة الخاص به.

إنشاء مفتاح API

افتح صفحة تفاصيل حساب الخدمة وأنشئ مفتاحًا. اختر الأذونات التي يحتاجها هذا المفتاح تحديدًا (مجموعة فرعية من أذونات الحساب) ومدة انتهاء الصلاحية — 30 أو 90 أو 365 يومًا، أو مدة مخصصة. انتهاء الصلاحية إلزامي.يبدأ السر الخاص بالمفتاح بـ lsk_live_ ويُعرض مرة واحدة فقط. انسخه إلى مدير أسرار فورًا؛ إذ لا يمكن استرجاعه لاحقًا.

لا تُضمِّن أسرار مفاتيح API في أنظمة التحكم في الإصدارات ولا تدرجها في الشيفرة من جهة العميل. يمكن لأي شخص يملك السر أن يتصرف بأذونات المفتاح.

اختيار المنطقة

استدعِ المضيف الإقليمي /v1 الذي يطابق موقع إقامة بيانات المؤسسة. تعمل المفاتيح للمصادقة على ذلك المضيف فقط.

المنطقة	عنوان URL الأساسي
US	`https://api.us-east-1.livingsecurity.ai/v1`
EU	`https://api.eu-west-1.livingsecurity.ai/v1`

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

إرسال أول طلب

حمِّل LIVING_SECURITY_API_KEY من مدير الأسرار إلى بيئة العملية التي ترسل الطلب. تقرؤه الأمثلة أدناه دون تضمين سر في الشيفرة المصدرية. في Python، ثبّت requests أولًا.استدعِ واجهة API مع وضع السر في حقل كلمة المرور أو حقل اسم المستخدم ضمن مصادقة HTTP Basic — يعمل أي منهما، لذا يمكن للعملاء الذين يشترطون تعبئة الحقلين (مثل موصل Web في Power BI) وضع عنصر نائب مثل apikey في الحقل الآخر.

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \
  -H "Living-Security-Version: 2026-07-01"

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}:" \
  -H "Living-Security-Version: 2026-07-01"

import os
import requests

BASE = "https://api.eu-west-1.livingsecurity.ai/v1"

response = requests.get(
    f"{BASE}/organization",
    auth=("apikey", os.environ["LIVING_SECURITY_API_KEY"]),
    headers={"Living-Security-Version": "2026-07-01"},
    timeout=(5, 30),
    allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 200:
    raise RuntimeError("Unexpected response; check your regional API URL")
print(response.json())

تعيد الاستجابة الناجحة بيانات مؤسستك:

Response

{
  "id": "1e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
  "object": "organization",
  "name": "Example Corp",
  "region": "eu",
  "plan": "enterprise",
  "subscription_status": "active",
  "created_at": "2024-03-12T18:04:11.000Z"
}

إذا حصلت على هذه الاستجابة، فإن بيانات اعتمادك تعمل. كما يظهر الطلب في علامة التبويب سجلات الطلبات في Developer Hub خلال لحظات.

تعمل أيضًا مصادقة Bearer باستخدام السر نفسه (Authorization: Bearer lsk_live_...). وُجدت مصادقة Basic لتتمكن الأدوات التي تدعم اسم المستخدم/كلمة المرور فقط — مثل موصل Web في Power BI — من الاتصال.

كيف تعمل المصادقة

تحدد بيانات الاعتماد المؤسسة. لا تحتوي طلبات /v1 على محدد للمستأجر: لا جزء مسار للمؤسسة ولا ترويسة للمؤسسة. يُرفض إرسال ترويسة x-organization-id مع الخطأ invalid_request. ويجب أن يطابق المضيف منطقة تلك المؤسسة. راجع المناطق.
تُفحص الأذونات لكل عملية. تتطلب كل عملية /v1 إذنًا مسمى (على سبيل المثال، تتطلب GET /v1/organization الإذن organization:read). يحصل المفتاح الذي يفتقر إلى الإذن على 403 مع الرمز insufficient_permission.
تنتهي صلاحية المفاتيح ويمكن تدويرها دون أي توقف. راجع مفاتيح API لمعرفة التدوير مع فترة تداخل.

قراءة استجابات الأخطاء

كل خطأ /v1 هو application/problem+json (RFC 9457) مع رمز آلي ثابت. على سبيل المثال، يعيد الطلب الذي يفتقر إلى بيانات اعتماد أو يحمل بيانات اعتماد غير معروفة ما يلي:

401 Unauthorized

{
  "type": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "No valid API credential was provided.",
  "code": "unauthorized",
  "request_id": "req_...",
  "doc_url": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized",
  "retryable": false
}

اعتمد في المعالجة الشرطية على code وليس على detail. اتبع doc_url لمعرفة خطوات الحل، وأرفق request_id عند التواصل مع الدعم — فهو يطابق ترويسة الاستجابة Request-Id وسجلات الطلبات في Developer Hub. تجد المجموعة الكاملة للرموز في مرجع الأخطاء.

إصدارات العقد

تعيد كل استجابة إصدار العقد الذي خدمها في الترويسة Living-Security-Version، إلى جانب ترويسة Request-Id لأغراض الربط. يمكنك تثبيت الطلب على إصدار عقد منشور حسب التاريخ:

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \
  -H "Living-Security-Version: 2026-07-01"

يُحدَّد الإصدار بهذا الترتيب: ترويسة الطلب إن وُجدت، وإلا الإصدار الافتراضي المثبت لحساب الخدمة، وإلا أحدث إصدار منشور. يؤدي طلب إصدار غير منشور (أو تجاوز تاريخ إيقافه) إلى 400 مع الرمز unsupported_version. تجد الإصدارات المنشورة وتغييراتها في سجل تغييرات API.

استكشاف أخطاء أول طلب وإصلاحها

النتيجة	الإجراء التالي
`401 unauthorized`	تحقق من السر وتاريخ انتهاء صلاحيته ومنطقة المؤسسة. لا تجرّب مضيفات أخرى باستخدام بيانات اعتماد فعلية.
`403 insufficient_permission`	امنح `organization:read` لكل من حساب الخدمة ومفتاحه.
`400 unsupported_version`	اختر إصدارًا منشورًا من سجل التغييرات.
`429 rate_limited`	انتظر `Retry-After`؛ واتبع مثال إعادة المحاولة المحدودة.
انتهاء مهلة الشبكة	تحقق من الاتصال وأعد محاولة هذه القراءة ضمن ميزانية إعادة المحاولة الخاصة بتطبيقك.

بالنسبة إلى الأخطاء الأخرى، اتبع doc_url الوارد في الاستجابة. احتفظ بـ Request-Id من أجل الدعم؛ ولا تُدرج ترويسة Authorization أو مفتاح API في أي تذكرة.

الخطوات التالية

المناطق

اختر مضيف /v1 في US أو EU للمؤسسة.

ترقيم الصفحات

تصفح القوائم باستخدام page_token وغلاف القائمة.

حدود المعدل

افهم ميزانيات الطلبات وتعامل مع استجابات 429.

مرجع الأخطاء

كل رمز خطأ وحالة HTTP الخاصة به وكيفية حله.

Developer Hub

أدر حسابات الخدمة ومفاتيح API وسجلات الطلبات.

مركز المطورين

واجهة برمجة التطبيقات العامة v1

مرجع واجهة برمجة التطبيقات v1

المتطلبات الأساسية

إنشاء بيانات الاعتماد

كيف تعمل المصادقة

قراءة استجابات الأخطاء

إصدارات العقد

استكشاف أخطاء أول طلب وإصلاحها

الخطوات التالية

المناطق

ترقيم الصفحات

حدود المعدل

مرجع الأخطاء

Developer Hub

مركز المطورين

واجهة برمجة التطبيقات العامة v1

مرجع واجهة برمجة التطبيقات v1

​المتطلبات الأساسية

​إنشاء بيانات الاعتماد

​كيف تعمل المصادقة

​قراءة استجابات الأخطاء

​إصدارات العقد

​استكشاف أخطاء أول طلب وإصلاحها

​الخطوات التالية

المناطق

ترقيم الصفحات

حدود المعدل

مرجع الأخطاء

Developer Hub

المتطلبات الأساسية

إنشاء بيانات الاعتماد

كيف تعمل المصادقة

قراءة استجابات الأخطاء

إصدارات العقد

استكشاف أخطاء أول طلب وإصلاحها

الخطوات التالية