API क्विकस्टार्ट

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

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

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

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

Create a service account

Developer Hub में Service accounts टैब खोलें और एक अकाउंट बनाएँ। उसे एक वर्णनात्मक नाम दें (उदाहरण के लिए reporting-pipeline) और वे अनुमतियाँ प्रदान करें जिनका उपयोग उसकी keys कर सकती हैं — इस गाइड के लिए organization:read पर्याप्त है।अकाउंट की अनुमतियाँ उसके अंतर्गत बनाई गई प्रत्येक key के लिए अधिकतम सीमा होती हैं: कोई key कभी भी अपने service account की अनुमति से अधिक कार्य नहीं कर सकती।

Create an API key

Service account का detail पेज खोलें और एक key बनाएँ। इस विशिष्ट key के लिए आवश्यक अनुमतियाँ (अकाउंट की अनुमतियों का एक उपसमूह) चुनें और एक समाप्ति अवधि चुनें — 30, 90 या 365 दिन, या कस्टम अवधि। समाप्ति अवधि अनिवार्य है।Key का secret lsk_live_ से शुरू होता है और केवल एक बार दिखाया जाता है। इसे तुरंत किसी secret manager में कॉपी करें; इसे बाद में पुनः प्राप्त नहीं किया जा सकता।

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

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 देखें। दूसरे क्षेत्र को भेजी गई वैध key unauthorized के रूप में विफल होती है। होस्ट बदलने के लिए नीचे दिए गए नमूने पर region ड्रॉपडाउन का उपयोग करें।

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 जैसा प्लेसहोल्डर रख सकते हैं।

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 के Request logs टैब में भी दिखाई देता है।

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

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

क्रेडेंशियल संगठन निर्धारित करता है। /v1 अनुरोधों में कोई tenant selector नहीं होता: न कोई organization path segment और न कोई organization हेडर। x-organization-id हेडर भेजने पर invalid_request के साथ अनुरोध अस्वीकार कर दिया जाता है। होस्ट का उस संगठन के क्षेत्र से मेल खाना फिर भी आवश्यक है। Regions देखें।
अनुमतियों की जाँच प्रत्येक ऑपरेशन पर होती है। प्रत्येक /v1 ऑपरेशन के लिए एक नामित अनुमति आवश्यक है (उदाहरण के लिए, GET /v1/organization के लिए organization:read आवश्यक है)। जिस key में अनुमति नहीं है, उसे कोड insufficient_permission के साथ 403 मिलता है।
Keys समाप्त होती हैं और बिना डाउनटाइम के रोटेट की जा सकती हैं। ओवरलैप विंडो के साथ रोटेशन के लिए API keys देखें।

त्रुटि प्रतिक्रियाएँ पढ़ना

प्रत्येक /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 के request logs से मेल खाता है। पूरा कोड सेट error reference में है।

कॉन्ट्रैक्ट संस्करण

प्रत्येक प्रतिक्रिया उस कॉन्ट्रैक्ट संस्करण को 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"

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

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

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

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

अगले चरण

Regions

संगठन के लिए US या EU /v1 होस्ट चुनें।

Pagination

page_token और list envelope के साथ सूचियों को क्रमवार पढ़ें।

Rate limits

अनुरोध बजट को समझें और 429 प्रतिक्रियाओं को संभालें।

Error reference

प्रत्येक त्रुटि कोड, उसका HTTP स्टेटस और उसे हल करने का तरीका।

Developer Hub

Service accounts, API keys और request logs प्रबंधित करें।

डेवलपर हब

पब्लिक API v1

API v1 संदर्भ

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

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

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

त्रुटि प्रतिक्रियाएँ पढ़ना

कॉन्ट्रैक्ट संस्करण

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

अगले चरण

Regions

Pagination

Rate limits

Error reference

Developer Hub

डेवलपर हब

पब्लिक API v1

API v1 संदर्भ

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

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

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

​त्रुटि प्रतिक्रियाएँ पढ़ना

​कॉन्ट्रैक्ट संस्करण

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

​अगले चरण

Regions

Pagination

Rate limits

Error reference

Developer Hub

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

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

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

त्रुटि प्रतिक्रियाएँ पढ़ना

कॉन्ट्रैक्ट संस्करण

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

अगले चरण