API Keys
एक डेवलपर API key वह क्रेडेंशियल है जिसे आपका कोड हर अनुरोध पर प्रस्तुत करता है। keys एडमिन पैनल में बनाई और प्रबंधित की जाती हैं — API के माध्यम से नहीं — और हर key एक एनवायरनमेंट, scopes का एक सेट, और एक सीक्रेट रखती है जो केवल एक बार प्रकट किया जाता है।
keys कहाँ प्रबंधित होती हैं
key प्रबंधन पैनल के इन-पैनल डेवलपर कंसोल में /org/developer-api पर रहता है। keys बनाना, सूचीबद्ध करना, रोटेट और निरस्त करना एडमिन क्रियाएँ हैं जो वहाँ आपके सामान्य साइन-इन सेशन के साथ की जाती हैं — वे जानबूझकर cuk_-प्रमाणित /v1 सरफेस का हिस्सा नहीं हैं (एक लीक हुई key कभी किसी अन्य key को बना या निरस्त नहीं कर सकती)। कंसोल Starter और उससे ऊपर उपलब्ध है; trial organizations keys नहीं बना सकते।
key फ़ॉर्मेट
एक key सीक्रेट का रूप cuk_<env>_<random> होता है — उदाहरण के लिए:
cuk_live_M8s2k...<random>इसके तीन भाग हैं:
| भाग | अर्थ |
|---|---|
cuk | ब्रांड प्रिफ़िक्स — हर Cuneiform Chat key cuk_ से शुरू होती है। |
<env> | एनवायरनमेंट: live या test। |
<random> | एक लंबा, URL-सुरक्षित रैंडम सीक्रेट। |
एनवायरनमेंट
हर key एक एनवायरनमेंट के लिए बनाई जाती है:
| एनवायरनमेंट | प्रिफ़िक्स | उपयोग |
|---|---|---|
live | cuk_live_ | आपके वास्तविक डेटा के विरुद्ध प्रोडक्शन ट्रैफ़िक। |
test | cuk_test_ | डेवलपमेंट और इंटीग्रेशन टेस्टिंग। |
एक-बार का प्रकटीकरण
पूरा सीक्रेट ठीक एक बार दिखाया जाता है — उस क्षण जब आप एक key बनाते या रोटेट करते हैं। उसके बाद, केवल key का प्रिफ़िक्स (cuk_<env>_) और उसके अंतिम चार अक्षर ही दिखाए जाते हैं, ताकि आप एक सूची में एक key को पहचान सकें बिना उसके पुनर्प्राप्त होने योग्य हुए।
यदि आप एक सीक्रेट खो देते हैं, तो आप इसे पुनर्प्राप्त नहीं कर सकते — एक नया पाने के लिए key को रोटेट करें (जो पुराने सीक्रेट को निरस्त कर देता है), या इसे निरस्त करके एक नया बनाएँ।
Scopes
एक key को पाँच scopes का एक उपसमुच्चय दिया जाता है। हर scope ऑपरेशनों का एक समूह अनलॉक करता है और key बनाने वाली रोल की RBAC अनुमतियों से अतिरिक्त रूप से सीमित होता है — एक key कभी इससे अधिक प्रदान नहीं कर सकती जितना इसका निर्माता पैनल में रखता है।
| Scope | क्या अनलॉक करता है | RBAC सीलिंग |
|---|---|---|
knowledge:read | डॉक्यूमेंट, फ़ोल्डर और tags को सूचीबद्ध, सर्च और प्राप्त करना। | कंटेंट read अनुमति आवश्यक। |
knowledge:write | डॉक्यूमेंट अपलोड, डिलीट और संगठित करना; फ़ोल्डर और tags बनाना/अपडेट करना/डिलीट करना। | कंटेंट upload + update अनुमतियाँ आवश्यक। |
agents:read | agents और उनके कॉन्फ़िगरेशन को सूचीबद्ध और प्राप्त करना। | agent read अनुमति आवश्यक। |
agents:write | agents बनाना और अपडेट करना; कॉन्फ़िगरेशन अपडेट करना; डिलीट और पुनर्स्थापित करना। | agent create + update अनुमतियाँ आवश्यक (डिलीट/पुनर्स्थापित करने के लिए agent-delete अनुमति भी आवश्यक)। |
agents:query | एक agent चलाना (POST /agents/{id}/query)। | agent read अनुमति आवश्यक। |
एक key को केवल उसके लिए आवश्यक scopes दें। एक अनुरोध जो अपने scopes के बाहर के endpoint को कॉल करता है, वह 403 permission_error (invalid_scope) से अस्वीकृत होता है।
keys का प्रबंधन (कंसोल में)
/org/developer-api पर डेवलपर कंसोल समर्थन करता है:
- बनाना — एक एनवायरनमेंट और scopes चुनें; सीक्रेट एक बार प्रकट किया जाता है।
- सूचीबद्ध करना — हर key का प्रिफ़िक्स, अंतिम चार अक्षर, scopes और स्टेटस देखें (सीक्रेट फिर कभी नहीं दिखाया जाता)।
- रोटेट करना — एक key के लिए एक नया सीक्रेट बनाएँ और पिछले को निरस्त करें। इसका उपयोग एक नियमित शेड्यूल पर या तुरंत करें यदि एक key लीक हुई हो।
- निरस्त करना — एक key को स्थायी रूप से अक्षम करें। एक निरस्त की गई key प्रस्तुत करने वाले अनुरोध
401से अस्वीकृत होते हैं।
इन किसी भी क्रिया के लिए कोई API endpoint नहीं है — डिज़ाइन के अनुसार वे केवल पैनल में हैं।