मुख्य कंटेंट पर जाएँ
Sursa Developers

कुंजी के स्कोप

स्कोप API के उस हिस्से का नाम है, जिसे कुंजी कॉल कर सकती है। API रेफ़रेंस का हर एंडपॉइंट बताता है कि उसे कौन-सा एक स्कोप चाहिए। जिस कुंजी के पास वह स्कोप नहीं है, उसकी रिक्वेस्ट कुछ भी पढ़ने या बदलने से पहले ही कोड api_keys.scope के साथ 403 से अस्वीकार कर दी जाती है।

स्कोप बताते हैं कि कुंजी कौन-से ऑपरेशन कॉल कर सकती है। वे ऑपरेशन कौन-से ऑब्जेक्ट देखते हैं, यह अब भी कुंजी का रोल, डेटा प्रोफ़ाइल और कलेक्शन तय करते हैं: cards:write और viewer रोल वाली कुंजी कार्ड नहीं बदल सकती, और एक कलेक्शन तक सीमित कुंजी बाक़ी कलेक्शन नहीं देखती।

स्कोप

स्कोपअनुमति देता है
cards:readकार्ड, कलेक्शन और फ़ोल्डर पढ़ना।
cards:writeकार्ड, कलेक्शन और फ़ोल्डर बनाना, बदलना और हटाना।
searchनॉलेज बेस में खोजना (POST /v1/search)।
askअसिस्टेंट से पूछना (POST /v1/ask, POST /v1/chat)।
import:writeसंगठन के कस्टम स्रोतों में लिखना: सिंक, बैच और डिलीशन, और उनकी स्थिति पढ़ना। स्रोत और उसकी कुंजियाँ बनाने के लिए admin चाहिए।
webhooks:manageवेबहुक मैनेज करना और इवेंट फ़ीड पढ़ना (GET /v1/webhook-events)। दोनों के लिए admin रोल भी चाहिए।
users:readयूज़र और ग्रुप पढ़ना।
users:writeयूज़र और ग्रुप बदलना।
analytics:readएनालिटिक्स पढ़ना।
audit:readऑडिट लॉग पढ़ना।
finance:readवित्तीय रिपोर्ट, इनवॉइस और भुगतान पढ़ना।
catalog:readसर्विस कैटलॉग पढ़ना।
files:readजनरेट की गई फ़ाइलें पढ़ना, जैसे एक्सपोर्ट किए गए जवाब।
files:writeजनरेट की गई फ़ाइलें बदलना और हटाना।
permissions:manageऑब्जेक्ट पर अनुमतियाँ देना और रद्द करना।
adminसंगठन की सेटिंग और उसकी API कुंजियाँ। admin वाली कुंजी के पास बाक़ी हर स्कोप भी होता है।

अपने मतलब से खोज और सवाल पढ़ना ही हैं: सिर्फ़ पढ़ सकने वाली कुंजी भी खोज सकती है और सवाल पूछ सकती है।

स्कोप चुनना

इंटीग्रेशन को वही स्कोप दें, जो वह इस्तेमाल करता है, और कुछ नहीं:

इंटीग्रेशनस्कोप
चैट टूल में सवाल-जवाब बॉटsearch, ask
आपके दस्तावेज़ सिस्टम से इम्पोर्टcards:write (कार्ड API) या import:write (कस्टम स्रोत)
डेटा वेयरहाउस में एक्सपोर्टcards:read, users:read, और इवेंट फ़ीड के लिए webhooks:manage
आपके HR सिस्टम से यूज़र बनानाusers:write

कुंजी बनाते समय सूची भेजें:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support bot", "role": "viewer", "scopes": ["search", "ask"]}'

पुराने स्कोप

स्कोप के बँटने से पहले बनी कुंजियाँ काम करती रहती हैं। उनके स्कोप read, write और admin इन सेट के बराबर हैं:

पुराना स्कोपमतलब
readcards:read, search, ask, users:read, analytics:read, finance:read, catalog:read, files:read
writeread में सब कुछ, और साथ में cards:write, files:write, users:write, permissions:manage
adminहर स्कोप

जो कुंजी स्पष्ट स्कोप के बिना बनाई गई है, उसे स्कोप उसके रोल से मिलते हैं: admin को admin; editor और verifier को write; viewer को read।

कुंजी के स्कोप देखना

GET /v1/me रिक्वेस्ट भेजने वाली कुंजी के स्कोप लौटाता है, उसके स्कोप चाहे जो हों। स्पष्ट स्कोप के बिना बनाई गई कुंजी के लिए ये उसके रोल के पुराने स्कोप होते हैं, जैसे read और write; ऊपर की तालिका बताती है कि उनमें क्या शामिल है। जब कोई ऑपरेशन api_keys.scope के साथ असफल होता है, तो error.message उस स्कोप का नाम बताता है, जो नहीं था।