> ## 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 क्विकस्टार्ट

> Developer Hub में एक service account और API key बनाएँ, Basic auth से प्रमाणीकरण करें, और Living Security Public API को अपना पहला अनुरोध भेजें।

Developer Hub में एक service account और एक API key बनाएँ, फिर अपना
पहला अनुरोध भेजें। यह क्विकस्टार्ट API-key प्रमाणीकरण का उपयोग करता है; इसके लिए
OAuth client की आवश्यकता नहीं है। यदि आपके इंटीग्रेशन को अल्पकालिक OAuth access token की आवश्यकता है, तो [Authentication](/hi/developers/v1/authentication) देखें।

## पूर्वापेक्षाएँ

* Living Security Dashboard तक Admin एक्सेस।
* Developer Hub, जो **Settings → Integrations & Developers →
  Developer Hub** के अंतर्गत दिखाई देना चाहिए।

## क्रेडेंशियल बनाएँ

<Steps>
  <Step title="Create a service account">
    Developer Hub में **Service accounts** टैब खोलें और एक
    अकाउंट बनाएँ। उसे एक वर्णनात्मक नाम दें (उदाहरण के लिए `reporting-pipeline`) और
    वे अनुमतियाँ प्रदान करें जिनका उपयोग उसकी keys कर सकती हैं — इस गाइड के लिए `organization:read`
    पर्याप्त है।

    अकाउंट की अनुमतियाँ उसके अंतर्गत बनाई गई प्रत्येक key के लिए अधिकतम सीमा होती हैं:
    कोई key कभी भी अपने service account की अनुमति से अधिक कार्य नहीं कर सकती।
  </Step>

  <Step title="Create an API key">
    Service account का detail पेज खोलें और एक key बनाएँ। इस विशिष्ट key के लिए आवश्यक
    अनुमतियाँ (अकाउंट की अनुमतियों का एक उपसमूह) चुनें और एक
    समाप्ति अवधि चुनें — 30, 90 या 365 दिन, या कस्टम अवधि। समाप्ति अवधि
    अनिवार्य है।

    Key का secret `lsk_live_` से शुरू होता है और केवल **एक बार** दिखाया जाता है। इसे तुरंत
    किसी secret manager में कॉपी करें; इसे बाद में पुनः प्राप्त नहीं किया जा सकता।

    <Warning>
      API key secrets को कभी भी version control में commit न करें और न ही क्लाइंट-साइड
      कोड में एम्बेड करें। secret रखने वाला कोई भी व्यक्ति key की अनुमतियों के साथ कार्य कर सकता है।
    </Warning>
  </Step>

  <Step title="Choose your region">
    संगठन की डेटा रेज़िडेंसी से मेल खाने वाले क्षेत्रीय `/v1` होस्ट को कॉल करें।
    Keys केवल उसी होस्ट पर प्रमाणित होती हैं।

    | Region | Base URL |
    | - | - |
    | US | `https://api.us-east-1.livingsecurity.ai/v1` |
    | EU | `https://api.eu-west-1.livingsecurity.ai/v1` |

    यदि आप सुनिश्चित नहीं हैं कि किस होस्ट का उपयोग करना है, तो [Regions](/hi/developers/v1/regions) देखें।
    दूसरे क्षेत्र को भेजी गई वैध key `unauthorized` के रूप में विफल होती है। होस्ट बदलने के लिए
    नीचे दिए गए नमूने पर region ड्रॉपडाउन का उपयोग करें।
  </Step>

  <Step title="Make your first request">
    `LIVING_SECURITY_API_KEY` को अपने secret manager से उस प्रोसेस के एनवायरनमेंट में लोड करें
    जो अनुरोध भेज रही है। नीचे दिए गए उदाहरण इसे स्रोत कोड में
    secret एम्बेड किए बिना पढ़ते हैं। Python के लिए पहले `requests` इंस्टॉल करें।

    API को कॉल करें और secret को HTTP Basic auth के password या username
    फ़ील्ड में दें — दोनों में से कोई भी काम करता है, इसलिए जिन क्लाइंट्स में दोनों फ़ील्ड भरना आवश्यक है (जैसे
    Power BI का Web connector), वे दूसरे फ़ील्ड में `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 के **Request logs** टैब में भी दिखाई देता है।
    </Check>
  </Step>
</Steps>

<Tip>
  उसी secret (`Authorization: Bearer
    lsk_live_...`) के साथ Bearer प्रमाणीकरण भी काम करता है। Basic auth इसलिए उपलब्ध है ताकि केवल
  username/password समझने वाले टूल — जैसे Power BI का Web connector — कनेक्ट हो सकें।
</Tip>

## प्रमाणीकरण कैसे काम करता है

* **क्रेडेंशियल संगठन निर्धारित करता है।** `/v1` अनुरोधों में कोई
  tenant selector नहीं होता: न कोई organization path segment और न कोई organization हेडर।
  `x-organization-id` हेडर भेजने पर `invalid_request` के साथ अनुरोध अस्वीकार कर दिया जाता है।
  होस्ट का उस संगठन के क्षेत्र से मेल खाना फिर भी आवश्यक है। [Regions](/hi/developers/v1/regions) देखें।
* **अनुमतियों की जाँच प्रत्येक ऑपरेशन पर होती है।** प्रत्येक `/v1` ऑपरेशन के लिए एक
  नामित अनुमति आवश्यक है (उदाहरण के लिए, `GET /v1/organization` के लिए
  `organization:read` आवश्यक है)। जिस key में अनुमति नहीं है, उसे कोड
  `insufficient_permission` के साथ `403` मिलता है।
* **Keys समाप्त होती हैं और बिना डाउनटाइम के रोटेट की जा सकती हैं।** ओवरलैप विंडो के साथ रोटेशन के लिए
  [API keys](/hi/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 के request logs से मेल खाता है। पूरा
कोड सेट [error reference](/hi/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>

संस्करण इस क्रम में निर्धारित होता है: अनुरोध हेडर, यदि मौजूद हो; अन्यथा
service account का पिन किया गया डिफ़ॉल्ट; अन्यथा नवीनतम प्रकाशित संस्करण।
ऐसे संस्करण का अनुरोध करने पर जो प्रकाशित नहीं है (या अपनी sunset तिथि पार कर चुका है),
कोड `unsupported_version` के साथ `400` लौटता है। प्रकाशित संस्करण और उनके
परिवर्तन [API changelog](/hi/developers/v1/changelog) में सूचीबद्ध हैं।

## अपने पहले अनुरोध की समस्या का निवारण करें

| परिणाम | अगली कार्रवाई |
| - | - |
| `401 unauthorized` | secret, उसकी समाप्ति अवधि और संगठन के क्षेत्र की जाँच करें। किसी वैध क्रेडेंशियल के साथ अन्य होस्ट आज़माएँ नहीं। |
| `403 insufficient_permission` | `organization:read` अनुमति service account और उसकी key, दोनों को प्रदान करें। |
| `400 unsupported_version` | [changelog](/hi/developers/v1/changelog) से कोई प्रकाशित संस्करण चुनें। |
| `429 rate_limited` | `Retry-After` तक प्रतीक्षा करें; [bounded retry example](/hi/developers/v1/rate-limits) का अनुसरण करें। |
| Network timeout | कनेक्टिविटी जाँचें और अपने एप्लिकेशन के retry budget के भीतर इस read को पुनः प्रयास करें। |

अन्य त्रुटियों के लिए, प्रतिक्रिया के `doc_url` का अनुसरण करें। सहायता के लिए `Request-Id` सुरक्षित रखें;
टिकट में Authorization हेडर या अपनी API key कभी शामिल न करें।

## अगले चरण

<CardGroup cols={2}>
  <Card title="Regions" href="/hi/developers/v1/regions">
    संगठन के लिए US या EU `/v1` होस्ट चुनें।
  </Card>

  <Card title="Pagination" href="/hi/developers/v1/pagination">
    `page_token` और list envelope के साथ सूचियों को क्रमवार पढ़ें।
  </Card>

  <Card title="Rate limits" href="/hi/developers/v1/rate-limits">
    अनुरोध बजट को समझें और `429` प्रतिक्रियाओं को संभालें।
  </Card>

  <Card title="Error reference" href="/hi/developers/v1/errors/overview">
    प्रत्येक त्रुटि कोड, उसका HTTP स्टेटस और उसे हल करने का तरीका।
  </Card>

  <Card title="Developer Hub" href="/hi/developers/developer-hub/overview">
    Service accounts, API keys और request logs प्रबंधित करें।
  </Card>
</CardGroup>


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