Legacy Public API

यह मार्गदर्शिका उन मौजूदा /api/v1 इंटीग्रेशन के बारे में है, जो API एक्सेस की को बेयरर टोकन से बदलते हैं। इनके क्रेडेंशियल और अनुरोध प्रारूप /v1 Public API से भिन्न हैं। नए इंटीग्रेशन के लिए API quickstart और Authentication से शुरुआत करें। नया /v1 API सर्विस-अकाउंट API कीज़ या OAuth एक्सेस टोकन का उपयोग करता है।

शुरू करने से पहले

आपको निम्नलिखित की आवश्यकता होगी:

Living Security का ऐसा एक्सेस, जो API एक्सेस-की प्रबंधन की अनुमति देता हो
Settings → Access Keys के अंतर्गत बनाई गई एक API एक्सेस की
क्रेडेंशियल बनाते समय एक बार दिखाया जाने वाला एक्सेस-की सीक्रेट
Living Security द्वारा आपके Public API क्रेडेंशियल के साथ उपलब्ध कराया गया API issuer ID
जिस संगठन को आप इंटीग्रेट कर रहे हैं, उसका क्षेत्रीय बेस URL
एक सर्वर-साइड रनटाइम और सीक्रेट मैनेजर

एक्सेस-की सीक्रेट को ब्राउज़र कोड, मोबाइल ऐप, सोर्स कंट्रोल, क्लाइंट-साइड एनवायरनमेंट वेरिएबल, टिकट या साझा लॉग में नहीं रखना चाहिए।

Access Keys डायलॉग एक बार दिखाया जाने वाला सीक्रेट प्रदर्शित करता है, लेकिन API issuer ID नहीं दिखाता। यदि Living Security ने आपके Public API क्रेडेंशियल के साथ issuer ID उपलब्ध नहीं कराया है, तो उसे Living Security Support से मँगवाएँ। issuer ID, एक्सेस की ID या संगठन ID नहीं है।

क्षेत्रीय होस्ट

Legacy अनुबंध इन क्षेत्रीय /api/v1 प्रोडक्शन होस्ट का उपयोग करता है:

क्षेत्र	बेस URL
US	`https://api.us-east-1.livingsecurity.ai/api/v1`
EU	`https://api.eu-west-1.livingsecurity.ai/api/v1`

Living Security संगठन को निर्धारित क्षेत्र का ही उपयोग करें। प्राधिकरण या उपलब्धता त्रुटि से बचने के लिए क्षेत्र न बदलें।

Legacy रिसोर्स

रिसोर्स	समर्थित ऑपरेशन
People	संगठन के लोगों को खोजना और किसी व्यक्ति की सदस्यता प्राप्त करना
API access keys	API एक्सेस कीज़ बनाना, सूचीबद्ध करना, रोटेट करना और रद्द करना

ऑपरेशन, पैरामीटर, अनुरोध, प्रतिक्रिया और स्कीमा की पूरी सूची के लिए Developers → Public API Reference का उपयोग करें। यदि कोई ऑपरेशन वहाँ नहीं है, तो वह वर्तमान में Public API का हिस्सा नहीं है।

Authentication

Public API एक्सेस के दो चरण हैं:

सीक्रेट एक्सेस की और API issuer ID को एक अल्पकालिक बेयरर टोकन और संगठन ID से बदलें।
प्रत्येक API अनुरोध के साथ बेयरर टोकन और संगठन ID भेजें।

आवश्यक अनुरोध हेडर ये हैं:

Authorization: Bearer <access-token>
x-organization-id: <organization-id>

संगठन हेडर में वही संगठन होना चाहिए, जो एक्सेस-की एक्सचेंज द्वारा लौटाया गया हो। कोई की किसी भी मनमानी संगठन ID तक एक्सेस को अधिकृत नहीं करती।

TypeScript SDK

वर्तमान मेजर संस्करण इंस्टॉल करें:

npm install @livingsecurity/sdk@^1

फिर की को एक्सचेंज करें और SDK को कॉन्फ़िगर करें:

import { configure, exchangeAccessKey } from "@livingsecurity/sdk";

const accessKeySecret = process.env.LS_API_ACCESS_KEY_SECRET;
const apiIssuerId = process.env.LS_API_ISSUER_ID;

if (!accessKeySecret || !apiIssuerId) {
  throw new Error("LS_API_ACCESS_KEY_SECRET and LS_API_ISSUER_ID are required");
}

const { accessToken, organizationId } = await exchangeAccessKey(
  accessKeySecret,
  apiIssuerId,
);

configure({
  baseUrl: "https://api.us-east-1.livingsecurity.ai/api/v1",
  accessToken,
  organizationId,
});

EU संगठन के लिए EU बेस URL का उपयोग करें। SDK एक्सचेंज का उद्देश्य सर्वर-साइड Node.js रनटाइम के लिए है।

सीधा REST अनुरोध

यदि आप एक्सचेंज SDK के बाहर करते हैं, तो प्रत्येक अनुरोध पर उसका बेयरर टोकन और संगठन ID भेजें:

curl --request GET \
  "https://api.us-east-1.livingsecurity.ai/api/v1/people/search?limit=1" \
  --header "Authorization: Bearer $LIVING_SECURITY_BEARER_TOKEN" \
  --header "x-organization-id: $LIVING_SECURITY_ORG_ID" \
  --header "Accept: application/json"

बेयरर टोकन अल्पकालिक होते हैं। नया टोकन प्राप्त करने के लिए एक्सेस की को दोबारा एक्सचेंज करें; बेयरर टोकन को स्थायी क्रेडेंशियल के रूप में सहेजकर न रखें।

एक्सेस-की जीवनचक्र

कीज़ का नाम उस इंटीग्रेशन या ऑटोमेशन के नाम पर रखें जिसके वे स्वामित्व में हैं।
एक्सेस-की फ़ॉर्म में उपलब्ध सबसे कम विशेषाधिकार वाले स्कोप चुनें।
एक बार दिखाया जाने वाला सीक्रेट तुरंत सुरक्षित रखें; निर्माण या रोटेशन के बाद उसे पुनः प्राप्त नहीं किया जा सकता।
की को Settings → Access Keys के माध्यम से रोटेट करें और पुराने क्रेडेंशियल को रद्द करने से पहले उसका प्रतिस्थापन तैनात करें।
जो कीज़ अब उपयोग में नहीं हैं या जिनका सीक्रेट उजागर हो गया हो सकता है, उन्हें रद्द करें।
जब आपके संगठन के लिए सर्विस-अकाउंट की उपलब्ध हो, तब गैर-मानवीय इंटीग्रेशन के लिए उसका उपयोग करें।

Pagination

People खोज limit, cursor, offset और includeTotal पैरामीटर का समर्थन करती है। क्रमिक ट्रैवर्सल के लिए पिछली प्रतिक्रिया द्वारा लौटाए गए कर्सर का उपयोग करना बेहतर है।

limit का डिफ़ॉल्ट मान 50 है और यह 1–100 स्वीकार करता है।
cursor पिछली प्रतिक्रिया से आगे बढ़ता है।
offset कुछ रिकॉर्ड छोड़ देता है और इसका डिफ़ॉल्ट मान 0 है।
includeTotal=true फ़िल्टर की गई सटीक गणना का अनुरोध करता है; गणना की आवश्यकता न होने पर इसे छोड़ दें।

एंडपॉइंट द्वारा लौटाए गए pagination ऑब्जेक्ट को पढ़ें। प्राप्त पंक्तियों की संख्या से अगला पृष्ठ न निकालें और स्वतंत्र रूप से पेजिनेट किए गए अनुरोधों को मिलाकर आंशिक परिणामों को स्वयं सॉर्ट न करें।

त्रुटियाँ

दस्तावेज़ में वर्णित JSON त्रुटियाँ इस सामान्य रूप का उपयोग करती हैं:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

message एक स्ट्रिंग या सत्यापन संदेशों की ऐरे हो सकता है।

स्टेटस	अर्थ	प्रतिक्रिया
`400`	अमान्य पैरामीटर या अनुरोध बॉडी	बताई गई सत्यापन त्रुटियों को ठीक करें
`401`	बेयरर टोकन अनुपस्थित, अमान्य या समाप्त हो चुका है	एक्सेस की को दोबारा एक्सचेंज करें और एक बार पुनः प्रयास करें
`403`	क्रेडेंशियल के पास अनुमति या संगठन एक्सेस नहीं है	की स्कोप और संगठन संदर्भ जाँचें
`404`	अधिकृत संगठन में रिसोर्स मौजूद नहीं है	रिसोर्स ID और संगठन सत्यापित करें
`408`	अनुरोध का समय समाप्त हो गया	सीमित एक्सपोनेंशियल बैकऑफ़ के साथ पुनः प्रयास करें
`429`	दर सीमा पूरी हो गई	कम से कम `Retry-After` (यदि मौजूद हो) जितनी प्रतीक्षा करें
`5xx`	अस्थायी सेवा विफलता	सुरक्षित रीड के लिए सीमित एक्सपोनेंशियल बैकऑफ़ के साथ पुनः प्रयास करें

क्यूरेटेड अनुबंध वर्तमान में कोई एक सार्वभौमिक संख्यात्मक दर सीमा प्रकाशित नहीं करता, और न ही प्रत्येक ऑपरेशन के लिए request-ID प्रतिक्रिया हेडर की गारंटी देता है। सहायता का अनुरोध करते समय UTC समय, मेथड, पाथ, स्टेटस और सैनिटाइज़ की गई प्रतिक्रिया बॉडी साथ में दें। create, rotate, revoke या delete ऑपरेशन को स्वचालित रूप से पुनः प्रयास न करें, जब तक कि ऑपरेशन में idempotency स्पष्ट रूप से दस्तावेज़ीकृत न हो। अस्पष्ट नेटवर्क विफलता के बाद रिसोर्स की वर्तमान स्थिति जाँचें।

संगतता और Deprecation

V1 डिफ़ॉल्ट रूप से योगात्मक (additive) रूप से विकसित होता है। क्लाइंट को अज्ञात प्रतिक्रिया फ़ील्ड की अनदेखी करनी चाहिए। किसी ब्रेकिंग परिवर्तन के लिए दस्तावेज़ीकृत माइग्रेशन पथ आवश्यक है; deprecated ऑपरेशन माइग्रेशन अवधि के दौरान उनके कारण, उपलब्ध होने पर प्रतिस्थापन और sunset तिथि के साथ रेफ़रेंस में बने रहते हैं। SDK को संगत मेजर संस्करण पर पिन करें और अपग्रेड करने से पहले उसके रिलीज़ नोट्स की समीक्षा करें। स्कीमा के स्रोत के रूप में जेनरेट किए गए Public API Reference को मानें, फ़र्स्ट-पार्टी ऐप क्लाइंट को नहीं।

Public API, MCP और वेब एप्लिकेशन

सरफ़ेस	उपयोग	संगतता मॉडल
Public API	ग्राहक सिस्टम, पार्टनर और बाहरी ऑटोमेशन	स्थिर, संस्करणबद्ध रिसोर्स
MCP	अनुमति-आधारित AI-टूल इंटरैक्शन	टूल अनुबंध और संक्षिप्त संरचित आउटपुट
Web application	Living Security उत्पाद में मानवीय वर्कफ़्लो	ऐप-स्वामित्व वाले अनुबंध, जो UI के साथ बदल सकते हैं

किसी AI टूल को Living Security से कनेक्ट करने के लिए MCP Integration देखें।

सहायता प्राप्त करें

निम्नलिखित जानकारी के साथ Living Security Support से संपर्क करें:

संगठन और क्षेत्र
SDK का नाम और संस्करण, यदि उपयोग किया गया हो
UTC टाइमस्टैम्प, मेथड और पाथ
HTTP स्टेटस और सैनिटाइज़ की गई त्रुटि बॉडी

एक्सेस-की सीक्रेट, बेयरर टोकन या निजी ग्राहक डेटा कभी शामिल न करें।

API Access Keys

API क्रेडेंशियल बनाएँ, रोटेट करें और रद्द करें।

MCP Integration

Model Context Protocol के माध्यम से समर्थित AI टूल कनेक्ट करें।

पब्लिक API

पब्लिक API संदर्भ

शुरू करने से पहले

क्षेत्रीय होस्ट

Legacy रिसोर्स

Authentication

TypeScript SDK

सीधा REST अनुरोध

एक्सेस-की जीवनचक्र

त्रुटियाँ

संगतता और Deprecation

Public API, MCP और वेब एप्लिकेशन

सहायता प्राप्त करें

संबंधित

API Access Keys

MCP Integration

पब्लिक API

पब्लिक API संदर्भ

​शुरू करने से पहले

​क्षेत्रीय होस्ट

​Legacy रिसोर्स

​Authentication

​TypeScript SDK

​सीधा REST अनुरोध

​एक्सेस-की जीवनचक्र

​Pagination

​त्रुटियाँ

​संगतता और Deprecation

​Public API, MCP और वेब एप्लिकेशन

​सहायता प्राप्त करें

​संबंधित

API Access Keys

MCP Integration

शुरू करने से पहले

क्षेत्रीय होस्ट

Legacy रिसोर्स

Authentication

TypeScript SDK

सीधा REST अनुरोध

एक्सेस-की जीवनचक्र

Pagination

त्रुटियाँ

संगतता और Deprecation

Public API, MCP और वेब एप्लिकेशन

सहायता प्राप्त करें

संबंधित