ऑथेंटिकेशन

Sursa API की हर रिक्वेस्ट Authorization हेडर में API कुंजी, या किसी ऐप का OAuth ऐक्सेस टोकन, लेकर जाती है:

Authorization: Bearer kb_3f9c…

कुंजी संगठन की पहचान करती है और तय करती है कि रिक्वेस्ट क्या देख और बदल सकती है: उसका रोल, उसके स्कोप, उसकी डेटा प्रोफ़ाइल और उसके कलेक्शन। API के पते पर न सेशन हैं, न कुकी। हर रिक्वेस्ट का ऑथेंटिकेशन अलग से होता है, इसलिए आप एक ही कुंजी से समानांतर रिक्वेस्ट और कई सर्वर से रिक्वेस्ट भेज सकते हैं।

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"

पुराने इंटीग्रेशन कुंजी को इसके बजाय X-API-Key हेडर में भेज सकते हैं। इसे अब भी स्वीकार किया जाता है, पर नए कोड में Authorization: Bearer इस्तेमाल करें।

क्रेडेंशियल के प्रकार

क्रेडेंशियल	कैसा दिखता है	कहाँ काम करता है
संगठन की API कुंजी	`kb_…`	API का हर एंडपॉइंट, उसके रोल, स्कोप, डेटा प्रोफ़ाइल और कलेक्शन की सीमा में।
कस्टम स्रोत की कुंजी	`kbsrc_…`	सिर्फ़ उसके अपने कस्टम स्रोत के पुश एंडपॉइंट (`/v1/push/sources/{source_id}/…`)।
OAuth ऐक्सेस टोकन	`kbat_…`	API रेफ़रेंस के एंडपॉइंट, टोकन के स्कोप की सीमा में। ऑथराइज़ेशन कोड के साथ `POST /oauth/token` से मिला टोकन उस कर्मचारी की ओर से काम करता है, जिसने सहमति दी; `client_credentials` टोकन API कुंजी की तरह संगठन की ओर से काम करता है। यह 1 घंटे के लिए मान्य होता है।

ये सभी एक ही तरह भेजे जाते हैं। कस्टम स्रोत की कुंजी अपने स्रोत के बाहर कुछ भी पढ़, खोज या बदल नहीं सकती; इसे वहाँ इस्तेमाल करें, जहाँ कुंजी किसी तीसरे पक्ष के पास रहती है, जैसे इंटीग्रेशन प्लैटफ़ॉर्म।

ऑथेंटिकेशन के एरर

स्टेटस और कोड	इसका मतलब	क्या करें
`401` `auth.not_authenticated`	कुंजी नहीं है, उसमें टाइपिंग की ग़लती है, या वह रद्द की जा चुकी है।	हेडर और कुंजी का मान जाँचें।
`401` `api_keys.expired`	कुंजी की मियाद ख़त्म हो चुकी है।	नई कुंजी बनाएँ और पुरानी की जगह उसे लगाएँ।
`401` `sources.push_key_invalid`	कस्टम स्रोत की कुंजी ग़लत है, रद्द की जा चुकी है या किसी दूसरे स्रोत की है।	कुंजी और पाथ में स्रोत की ID जाँचें।
`401` `oauth.token_expired`	OAuth ऐक्सेस टोकन की मियाद ख़त्म हो चुकी है।	रिफ़्रेश टोकन से नया टोकन लें।
`403` `api_keys.scope`	कुंजी के पास इस ऑपरेशन का स्कोप नहीं है।	स्कोप जोड़ें, या ऐसी कुंजी इस्तेमाल करें जिसके पास वह हो।
`403` `api_keys.feature_disabled`	संगठन के प्लान में API कुंजियाँ शामिल नहीं हैं।	संगठन के एडमिन से संपर्क करें।
`403` `api_keys.ip_not_allowed`	रिक्वेस्ट ऐसे पते से आई है, जो कुंजी के अनुमत पतों में नहीं है।	किसी अनुमत नेटवर्क से कॉल करें, या कुंजी के पते बदलें।
`403` `api_keys.mcp_only`	निजी MCP कुंजी `/mcp` एंडपॉइंट के बाहर इस्तेमाल की गई।	API के लिए संगठन की API कुंजी इस्तेमाल करें।
`403` `oauth.operation_not_allowed`	यह ऑपरेशन पब्लिक API का हिस्सा नहीं है, इसलिए OAuth टोकन उसे कॉल नहीं कर सकता।	API रेफ़रेंस का कोई ऑपरेशन इस्तेमाल करें।
`403` `org.suspended`	संगठन निलंबित है। उसका डेटा सुरक्षित रखा जाता है।	संगठन के एडमिन से संपर्क करें।

403 का मतलब है कि रिक्वेस्ट का ऑथेंटिकेशन हो गया, पर उसकी अनुमति नहीं है। जिस ऑब्जेक्ट को देखने की अनुमति कुंजी के पास नहीं है, उसके लिए 404 लौटता है, ठीक वैसे ही जैसे मौजूद न होने वाले ऑब्जेक्ट के लिए, ताकि कुंजी यह न जान सके कि उसके ऐक्सेस के बाहर क्या है।

डेटा प्रोफ़ाइल की तरह रिक्वेस्ट चलाना

admin रोल वाली कुंजी जाँच सकती है कि लोगों के किसी दूसरे ग्रुप को क्या दिखेगा: X-View-As हेडर रिक्वेस्ट को किसी डेटा प्रोफ़ाइल की तरह, और चाहें तो किसी रोल की तरह भी, चलाता है।

curl "https://api.sursa.com/v1/cards?limit=20" \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "X-View-As: employee:viewer"

इस मोड में रिक्वेस्ट सिर्फ़ पढ़ती हैं: कोई भी बदलाव कोड view_as.read_only के साथ 403 लौटाता है। OAuth टोकन, या admin रोल के बिना कुंजी, X-View-As इस्तेमाल नहीं कर सकती: जवाब में कोड view_as.admin_key_required के साथ 403 लौटता है। जो हेडर किसी मौजूदा प्रोफ़ाइल का नाम नहीं देता, उस पर कोड view_as.invalid_header के साथ 400 लौटता है।

ब्राउज़र ऐप्लिकेशन

API किसी भी वेब ओरिजिन से रिक्वेस्ट की अनुमति देता है (Access-Control-Allow-Origin: *) और कभी कुकी इस्तेमाल नहीं करता, इसलिए कोई पेज इसे fetch से कॉल कर सकता है। तब कुंजी पेज में रहती है और उसे इस्तेमाल करने वाले हर व्यक्ति को दिखती है। ब्राउज़र से API सिर्फ़ ऐसी कुंजी से कॉल करें, जिसे आप उन यूज़र को दिखाने के लिए तैयार हों, जैसे पब्लिक कलेक्शन तक सीमित viewer कुंजी, या ब्राउज़र और Sursa के बीच अपना सर्वर रखें।

सिर्फ़ कर्मचारी क्या कर सकता है

संगठन की API कुंजी संगठन की ओर से काम करती है, किसी व्यक्ति की ओर से नहीं। API के दो हिस्से लोगों से जुड़े हैं, इसलिए वे सिर्फ़ ऐसे टोकन से काम करते हैं, जो किसी कर्मचारी की ओर से काम करता है: Sursa में सेशन, या कर्मचारी की सहमति से जारी OAuth ऐक्सेस टोकन।

बातचीत किसी व्यक्ति की होती है। संगठन की API कुंजी GET /v1/conversations में सिर्फ़ वे बातचीत देखती है, जो उसने ख़ुद शुरू कीं। पब्लिक API में बातचीत शुरू करने वाला कोई ऑपरेशन नहीं है, इसलिए कुंजी के लिए यह सूची आम तौर पर ख़ाली होती है, और कर्मचारियों की बातचीत उसे कभी नहीं दिखती। बातचीत के बिना सवाल, POST /v1/ask या POST /v1/chat से, स्कोप ask वाली किसी भी कुंजी से काम करते हैं। किसी कर्मचारी की बातचीत की सूची पाने और GET /v1/conversations/{conv_id} से उनमें से किसी एक का इतिहास पढ़ने के लिए, उस कर्मचारी की ओर से OAuth टोकन से API कॉल करें। टोकन सिर्फ़ उसी कर्मचारी की अपनी बातचीत देखता है; किसी भी दूसरी बातचीत पर कोड conversations.not_found के साथ 404 लौटता है।

कार्ड सिर्फ़ कर्मचारी सत्यापित करता है। सत्यापन इस बात की पुष्टि है कि किसी व्यक्ति ने कंटेंट जाँचा, इसलिए POST /v1/cards/{card_id}/verification/verify और POST /v1/cards/{card_id}/verify के लिए सेशन, या ऐसे कर्मचारी की ओर से OAuth टोकन चाहिए, जो कार्ड को सत्यापित कर सकता है। संगठन की API कुंजी या client_credentials टोकन के साथ ये ऑपरेशन कोड cards.verify_user_account_required के साथ 400 लौटाते हैं। सामान्य जाँचें पहले होती हैं: जो कार्ड कुंजी नहीं देख सकती, उस पर 404 लौटता है, और जिस कुंजी को उसे सत्यापित करने की अनुमति नहीं है, उस पर 403।