> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livingsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> أنشئ حساب خدمة ومفتاح API في Developer Hub، ثم صادِق باستخدام مصادقة Basic، وأرسل أول طلب إلى واجهة Living Security Public API.

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

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

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

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

<Steps>
  <Step title="إنشاء حساب خدمة">
    في Developer Hub، افتح علامة التبويب **حسابات الخدمة** وأنشئ
    حسابًا. امنحه اسمًا وصفيًا (على سبيل المثال `reporting-pipeline`) ثم
    امنحه الأذونات التي يمكن لمفاتيحه استخدامها — ويكفي لهذا الدليل الإذن `organization:read`.

    تمثل أذونات الحساب الحد الأقصى لكل مفتاح يُنشأ ضمنه:
    فلا يمكن لأي مفتاح أن يفعل أكثر مما يسمح به حساب الخدمة الخاص به.
  </Step>

  <Step title="إنشاء مفتاح API">
    افتح صفحة تفاصيل حساب الخدمة وأنشئ مفتاحًا. اختر
    الأذونات التي يحتاجها هذا المفتاح تحديدًا (مجموعة فرعية من أذونات الحساب) ومدة
    انتهاء الصلاحية — 30 أو 90 أو 365 يومًا، أو مدة مخصصة. انتهاء الصلاحية
    إلزامي.

    يبدأ السر الخاص بالمفتاح بـ `lsk_live_` ويُعرض **مرة واحدة** فقط. انسخه
    إلى مدير أسرار فورًا؛ إذ لا يمكن استرجاعه لاحقًا.

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

  <Step title="اختيار المنطقة">
    استدعِ المضيف الإقليمي `/v1` الذي يطابق موقع إقامة بيانات
    المؤسسة. تعمل المفاتيح للمصادقة على ذلك المضيف فقط.

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

    راجع [المناطق](/ar/developers/v1/regions) إذا لم تكن متأكدًا من المضيف الذي
    ينبغي استخدامه. يفشل المفتاح الصالح المُرسل إلى المنطقة الأخرى بالخطأ `unauthorized`. استخدم
    القائمة المنسدلة للمنطقة في العينة أدناه لتبديل المضيف.
  </Step>

  <Step title="إرسال أول طلب">
    حمِّل `LIVING_SECURITY_API_KEY` من مدير الأسرار إلى بيئة
    العملية التي ترسل الطلب. تقرؤه الأمثلة أدناه دون تضمين
    سر في الشيفرة المصدرية. في Python، ثبّت `requests` أولًا.

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

    <CodeGroup>
      ```bash cURL theme={null}
      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"
      ```

      ```bash cURL (key as username) theme={null}
      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"
      ```

      ```python Python theme={null}
      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())
      ```
    </CodeGroup>

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

    ```json Response theme={null}
    {
      "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"
    }
    ```

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

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

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

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

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

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

```json 401 Unauthorized theme={null}
{
  "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. تجد المجموعة الكاملة
للرموز في [مرجع الأخطاء](/ar/developers/v1/errors/overview).

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

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

يمكنك تثبيت الطلب على إصدار عقد منشور حسب التاريخ:

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

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

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

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

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

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

<CardGroup cols={2}>
  <Card title="المناطق" href="/ar/developers/v1/regions">
    اختر مضيف `/v1` في US أو EU للمؤسسة.
  </Card>

  <Card title="ترقيم الصفحات" href="/ar/developers/v1/pagination">
    تصفح القوائم باستخدام `page_token` وغلاف القائمة.
  </Card>

  <Card title="حدود المعدل" href="/ar/developers/v1/rate-limits">
    افهم ميزانيات الطلبات وتعامل مع استجابات `429`.
  </Card>

  <Card title="مرجع الأخطاء" href="/ar/developers/v1/errors/overview">
    كل رمز خطأ وحالة HTTP الخاصة به وكيفية حله.
  </Card>

  <Card title="Developer Hub" href="/ar/developers/developer-hub/overview">
    أدر حسابات الخدمة ومفاتيح API وسجلات الطلبات.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.