API कुंजियाँ और स्कोप

Sursa API की हर रिक्वेस्ट आपके संगठन की API कुंजी से की जाती है। कुंजी संगठन की होती है, किसी व्यक्ति की नहीं: उसे बनाने वाला कर्मचारी कंपनी छोड़ दे, तब भी वह काम करती रहती है, और वह क्या कर सकती है, यह कुंजी पर ही तय होता है।

कुंजी को क्या करने की अनुमति है

कुंजी की तीन सेटिंग तय करती हैं कि उसके साथ की गई रिक्वेस्ट क्या देख और बदल सकती है। हर सेटिंग बाक़ी दोनों को सिर्फ़ और सीमित करती है।

सेटिंग	यह क्या नियंत्रित करती है
रोल	`admin`, `editor`, `verifier` या `viewer`, वही रोल जो लोगों के होते हैं। कुंजी वह कर सकती है, जो उस रोल वाला यूज़र कर सकता है।
स्कोप	API के कौन-से हिस्से कुंजी कॉल कर सकती है, उदाहरण के लिए `cards:read` या `webhooks:manage`। देखें कुंजी के स्कोप।
डेटा प्रोफ़ाइल	वैकल्पिक। कुंजी को नॉलेज की उन्हीं कैटेगरी तक सीमित करता है, जिनकी प्रोफ़ाइल अनुमति देती है, उस प्रोफ़ाइल वाले यूज़र की तरह।

कुंजी को कुछ कलेक्शन तक सीमित भी किया जा सकता है और उसकी मियाद ख़त्म होने की तारीख़ भी तय की जा सकती है। इन सीमाओं से बाहर की रिक्वेस्ट असफल होती है: स्कोप न होने पर कोड api_keys.scope के साथ 403 लौटता है, और जो ऑब्जेक्ट कुंजी को नहीं दिखता, उसके लिए 404 लौटता है, ठीक वैसे ही जैसे वह मौजूद ही न हो।

हर इंटीग्रेशन को उसकी अपनी कुंजी दें, उतने ही सीमित रोल और स्कोप के साथ, जितने उसे चाहिए। जो सिंक जॉब सिर्फ़ दस्तावेज़ लिखता है, उसे admin की ज़रूरत नहीं; रिपोर्टिंग जॉब को लिखने वाले स्कोप की ज़रूरत नहीं।

कुंजी बनाएँ

संगठन का एडमिन Sursa में Administration → API keys (एडमिनिस्ट्रेशन → API कुंजियाँ) में कुंजियाँ बनाता है, या admin रोल वाली कुंजी या सेशन से POST /v1/api-keys कॉल करके:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "role": "editor",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

रिस्पॉन्स में कुंजी का मान key में होता है। यह सिर्फ़ एक बार दिखाया जाता है: Sursa इसका सिर्फ़ हैश रखता है और इसे दोबारा नहीं दिखा सकता। कुंजी kb_ और उसके बाद 43 अक्षरों जैसी दिखती है; शुरुआती अक्षर (prefix) कुंजियों की सूची में दिखाए जाते हैं, ताकि आप कुंजियों को अलग-अलग पहचान सकें।

scopes के बिना कुंजी को उसके रोल के स्कोप मिलते हैं। उसे और सीमित करने के लिए scopes भेजें। expires_at के बिना कुंजी की मियाद ख़त्म नहीं होती।

कुंजियाँ गोपनीय रखें

कुंजियाँ सीक्रेट मैनेजर में या अपनी सर्विस के एनवायरनमेंट वेरिएबल में रखें, सोर्स कोड में कभी नहीं।
कुंजियाँ सिर्फ़ अपने सर्वर से इस्तेमाल करें। Sursa ब्राउज़र से भी रिक्वेस्ट स्वीकार करता है (CORS खुला है), पर वेब पेज में रखी कुंजी उसे खोलने वाले हर व्यक्ति को दिखती है।
कुंजी कभी URL में न भेजें। उसे सिर्फ़ Authorization हेडर में भेजें।
अगर कुंजी लीक हो जाए, तो उसे तुरंत रद्द करें और नई बनाएँ।

कुंजी जाँचें

GET /v1/me कुंजी, उसका रोल, असल में लागू स्कोप, डेटा प्रोफ़ाइल, मियाद और रेट लिमिट लौटाता है। यह किसी भी मान्य कुंजी के साथ काम करता है, उसके स्कोप चाहे जो हों, इसलिए इसे अपने इंटीग्रेशन के कनेक्शन टेस्ट के रूप में और 403 की जाँच करते समय इस्तेमाल करें।

कुंजी रोटेट करें

रोटेशन इंटीग्रेशन को रोके बिना कुंजी बदल देता है। सबसे तेज़ तरीक़ा है कुंजी को दोबारा जारी करना: POST /v1/api-keys/{key_id}/roll उसी कुंजी के लिए नया मान जारी करता है, उसी रोल, स्कोप, कलेक्शन और मियाद के साथ। पिछला मान overlap_hours तक काम करता रहता है (डिफ़ॉल्ट रूप से 24 घंटे, 168 तक), ताकि इस बीच आप नया मान डिप्लॉय कर सकें; POST /v1/api-keys/{key_id}/revoke-previous ओवरलैप अवधि पहले ही ख़त्म कर देता है।

इसके बजाय कुंजी को किसी दूसरी कुंजी से बदलने के लिए:

उसी रोल, स्कोप और डेटा प्रोफ़ाइल के साथ नई कुंजी बनाएँ।
नई कुंजी अपने इंटीग्रेशन में डिप्लॉय करें।
Administration → API keys में (या GET /v1/api-keys में last_used से) पुरानी कुंजी पर नज़र रखें, जब तक उसका इस्तेमाल बंद न हो जाए।
पुरानी कुंजी रद्द करें।

कुंजियों पर मियाद ख़त्म होने की तारीख़ तय करें और उससे पहले उन्हें रोटेट करें। कुंजी की मियाद ख़त्म होने से पहले Sursa संगठन के एडमिन को चेतावनी देता है; जिस कुंजी की मियाद ख़त्म हो चुकी है, वह कोड api_keys.expired के साथ 401 लौटाती है।

कुंजी रद्द करें

कुंजी Administration → API keys में या DELETE /v1/api-keys/{key_id} से रद्द करें। रद्द करना कुछ ही सेकंड में हर API सर्वर पर लागू हो जाता है। रद्द की गई कुंजी वाली रिक्वेस्ट कोड auth.not_authenticated के साथ 401 लौटाती हैं।

कस्टम स्रोत की कुंजियाँ

कस्टम स्रोत की अपनी तरह की कुंजी होती है। यह kbsrc_ से शुरू होती है, सिर्फ़ उसी एक स्रोत में दस्तावेज़ लिख सकती है, और कुछ भी पढ़ या खोज नहीं सकती। Zapier जैसे इंटीग्रेशन प्लैटफ़ॉर्म को देने के लिए यही सबसे सुरक्षित कुंजी है। इसे स्रोत के पेज पर API keys (स्रोत की API कुंजियाँ) में या POST /v1/sources/{source_id}/push-keys से बनाएँ।

जब कुंजियाँ उपलब्ध नहीं होतीं

API कुंजियाँ संगठन के प्लान का हिस्सा हैं। अगर प्लान में वे शामिल नहीं हैं, तो कुंजी बनाने पर और कुंजी वाली हर रिक्वेस्ट पर कोड api_keys.feature_disabled के साथ 403 लौटता है।