Admin API keys

व्यवस्थापक में कहाँ: System › Settings › API & AI agents (/agent/keys), टैब API keys। उसी पृष्ठ पर Connect an AI, Connected apps और Activity टैब हैं।

यह क्या करता है

एक व्यवस्थापक API कुंजी (उपसर्ग ak_) एक AI क्लाइंट या स्क्रिप्ट को आपके पैनल को बिल्कुल उन अनुमतियों के साथ प्रबंधित करने देती है जो आप इसे देते हैं। यह /v1/admin/ के अंतर्गत व्यवस्थापक API पर और व्यवस्थापक MCP समापन बिंदु /mcp/admin पर काम करती है। यह अन्य कहीं काम नहीं करती।

ग्राहक कुंजियों के समान नहीं

ग्राहक कस्टमर पोर्टल में vk_ से शुरू होने वाली की (keys) बनाते हैं (API keys and scopes)। वे केवल कस्टमर API और /mcp तक ही पहुँचती हैं। कस्टमर API पर ak_ की अस्वीकार कर दी जाती है, और एडमिन API पर vk_ की अस्वीकार कर दी जाती है।

आवश्यकताएं

आइटम	आवश्यकता
Role	आपको व्यवस्थापक के रूप में साइन इन होना चाहिए। कुंजियाँ अन्य कुंजियाँ नहीं बना सकतीं।
डेमो	डेमो पैनल पर पृष्ठ केवल पढ़ने के लिए है: कोई कुंजी बनाई या निरस्त नहीं की जा सकती।
पहुँच योग्यता	क्लाइंट को आपके पैनल पर https://cloud.example.com/mcp/admin या /v1/admin/... तक पहुँचना होगा (यदि आप IP प्रतिबंधों का उपयोग करते हैं तो अपने फ़ायरवॉल की जाँच करें)।

एक की (key) बनाएं

1. System › Settings › API & AI agents खोलें और API keys टैब पर रहें।

2. Create new key पर क्लिक करें।

3. फॉर्म भरें:

   फ़ील्ड	नियम
   Name	अधिकतम 60 वर्ण, उदाहरण के लिए "Claude Code on my laptop"।
   Scopes	कम से कम एक चुनें। Scopes देखें। केवल admin:read से शुरू करें।
   समाप्ति (Expiry)	1, 7, 30, 60 या 90 दिन। डिफ़ॉल्ट 30। अधिकतम 90। बिना समाप्ति वाली की नहीं बनाई जा सकती।
   IP रेंज (वैकल्पिक)	प्रति पंक्ति एक IPv4 या IPv6 पता या CIDR, उदाहरण के लिए 203.0.113.0/24 या 2001:db8::/48। अधिकतम 32। किसी भी IP की अनुमति देने के लिए खाली छोड़ें।
   प्रति मिनट कॉल	1 से 6000। डिफ़ॉल्ट 120।

4. Create key पर क्लिक करें। एक बॉक्स में की एक बार दिखाई देती है, उदाहरण के लिए ak_XXXX। इसे अभी कॉपी करें: NexCMP केवल एक हैश (hash) संग्रहीत करता है और इसे दोबारा कभी नहीं दिखा सकता।

5. I have saved the key पर क्लिक करें। Connect an AI टैब खोलें ताकि ऐसे तैयार-से-तैयार कमांड मिल सकें जिनमें आपकी अभी बनाई गई कुंजी पहले से मौजूद हो (केवल इसी पेज पर, इसे रीलोड करने तक)।

Scopes

एक कुंजी केवल उन्हीं टूल्स और एंडपॉइंट्स का उपयोग कर सकती है जिनकी उसके स्कोप अनुमति देते हैं। राइट स्कोप में रीड एक्सेस शामिल नहीं होता है: जिस कुंजी को पढ़ना और लिखना दोनों करना हो, उसे admin:read की भी आवश्यकता होती है।

Scope	यह क्या अनुमति देता है
admin:read	सेटिंग्स, कैटलॉग, ग्राहक, बिलिंग और लॉग पढ़ें। गुप्त डेटा (Secrets) कभी नहीं लौटाए जाते।
catalog:write	प्लान, ओएस टेम्पलेट्स, कोटा, डिस्काउंट कोड।
infra:write	इन्फ्रास्ट्रक्चर सोर्स (CloudStack, Proxmox), ज़ोन, सर्वर।
billing:write	पेमेंट गेटवे, मुद्रा, चालान (invoices), बैलेंस। धन संबंधी कार्रवाइयों के लिए पुष्टि आवश्यक है।
customers:write	ग्राहक और रीeller।
settings:write	सामान्य सेटिंग्स, ब्रांडिंग, ईमेल, कानूनी पृष्ठ, मॉड्यूल, सूचनाएं।
ai:write	AI प्रदाता और AI विशेषताएं।
secrets:write	पासवर्ड और API कुंजी लिखें। इन्हें सेट किया जा सकता है लेकिन कभी पढ़ा नहीं जा सकता।

गोपनीय कुंजी सेट करने के लिए दो स्कोप चाहिए

कोई भी कॉल जिसमें पासवर्ड, API कुंजी या टोकन मान (SMTP पासवर्ड, भुगतान कुंजी, टेलीग्राम बॉट टोकन, AI प्रदाता कुंजी, CloudStack या Proxmox क्रेडेंशियल्स) शामिल है, के लिए secrets:write और उस क्षेत्र के स्कोप (उदाहरण के लिए SMTP के लिए settings:write) की आवश्यकता होती है। यदि आप गुप्त कुंजियाँ स्वयं टाइप करना चाहते हैं, तो secrets:write को छोड़ दें और उन्हें एडमिन में दर्ज करें।

कुंजी रद्द करना

1. तालिका में कुंजी खोजें (स्थिति Active, Expired या Revoked; Last used समय और क्लाइंट दिखाता है)।
2. Revoke पर क्लिक करें और पुष्टि करें।

कुंजी तुरंत काम करना बंद कर देती है। रद्द करना स्थायी है; यदि आपको दोबारा आवश्यकता हो तो एक नई कुंजी बनाएं।

एक कुंजी कभी क्या नहीं कर सकती

कोई भी कुंजी इन क्षेत्रों तक कभी नहीं पहुँच सकती, चाहे इसके स्कोप कुछ भी हों। इनके लिए आपको एडमिन में लॉग इन होना आवश्यक है।

• प्रशासक उपयोगकर्ता, 2FA और साइन-इन सुरक्षा, एडमिन सत्र, और एडमिन API टोकन बनाएं या बदलें।
• एडमिन कुंजियाँ, OAuth कनेक्शन और AI खाते बनाएँ, सूचीबद्ध करें या रद्द करें, या AI Console का उपयोग करें।
• पैनल का बैकअप लें या पुनर्स्थापित करें, इसे अपडेट करें, या इसका लाइसेंस बदलें।
• ग्राहक या रीeller के रूप में लॉग इन करें, किसी ग्राहक का कंसोल खोलें, VM क्रेडेंशियल्स या kubeconfig पढ़ें, SSH कुंजी सेट करें, या पासवर्ड भेजें या रीसेट करें।
• नेटवर्क और रूटिंग मॉड्यूल (BGP, FRR, RTBH, XDP, इंटरफेस, स्टैटिक और पॉलिसी रूट, NAT) या बाहरी एजेंटों और पोर्टल इंटीग्रेशन को बदलें। ये केवल पढ़ने के लिए (read-only) हैं।
• demo_*, admin_*, होस्ट सूचियों, पासकी, री-ऑथेंटिकेशन और कैप्चा रहस्यों जैसी सेटिंग्स बदलें।

किसी नियम के अंतर्गत न आने वाली कोई भी चीज़ लिखने के लिए डिफ़ॉल्ट रूप से बंद होती है, और पढ़ने के लिए admin:read के साथ पढ़ने योग्य होती है।

ऐसी कार्रवाइयां जिन्हें आपकी पुष्टि की आवश्यकता होती है

ये केवल पूर्वावलोकन (preview) स्वीकृत करने के बाद सफल होती हैं (देखें Two-step confirmation):

• ग्राहक का बैलेंस या रीeller का वॉलेट बदलना, पैसे का भुगतान करना, बिलिंग रिकॉर्ड, विनिमय दर (exchange rate)।
• कीमतें बदलना (प्लान की कीमतें, बल्क प्लान निर्माण, इमेज और स्टोरेज प्राइसिंग) और डिस्काउंट या मनी कोड बनाना।
• पेमेंट गेटवे क्रेडेंशियल्स या CloudStack कनेक्शन सहेजना।
• कुछ भी हटाना, किसी ग्राहक को ब्लॉक करना या हटाना, ग्राहक की सीमाएं बदलना, किसी रीeller को निलंबित करना या बंद करना।
• ग्राहक सर्वर पर कार्रवाई करना, या किसी ग्राहक के लिए भुगतान वाला सर्वर बनाना।
• सामान्य सेटिंग्स के माध्यम से साइट-व्यापी स्विच, साइन-इन सुरक्षा सेटिंग्स या भुगतान सेटिंग्स बदलना।

Two-step confirmation

जब किसी कॉल को पुष्टि की आवश्यकता होती है, तो अभी कुछ नहीं बदलता। प्रतिक्रिया HTTP 428 होती है जिसमें confirm_required, एक confirm_token, एक preview (विधि, पथ, कारण, नए मान और, जब उपलब्ध हो, वर्तमान मान) और expires_in: 300 होता है।

1. क्लाइंट आपको पूर्वावलोकन (preview) दिखाता है।
2. आपके द्वारा स्वीकृत करने के बाद, यह X-Confirm-Token: <confirm_token> हेडर के साथ वही अनुरोध (वही विधि, पथ और बॉडी) दोहराता है। MCP टूल इसके बजाय confirm_token तर्क लेते हैं।
3. टोकन एक बार काम करता है और 5 मिनट के बाद समाप्त हो जाता है।

AI Chat के लिए एडमिन के अंदर बनाई गई कुंजियों की पुष्टि केवल स्क्रीन पर की जा सकती है: उत्तर में confirm_in: "ui" कहा जाता है और एडमिन में एक पुष्टिकरण कार्ड दिखाई देता है। AI इसे स्वीकृत नहीं कर सकता।

रेट लिमिट और IP नियम

• प्रति-मिनट सीमा पार होने पर कॉल rate_limited (HTTP 429) लौटाता है जिसके साथ Retry-After: 60 होता है।
• IP रेंज सेट होने पर, किसी अन्य पते से आने वाली कॉल ip_not_allowed (HTTP 403) लौटाती हैं।

Activity log

Activity टैब किसी कुंजी के साथ किए गए प्रत्येक कॉल को सबसे नए से शुरू करके सूचीबद्ध करता है: समय, कुंजी, क्लाइंट, यह कैसे आया (http, mcp, chat, cli, confirm, preview), मेथड और पाथ, टूल, HTTP स्टेटस, आईपी और (मास्क किए गए) विवरण। आप पाथ, टूल या कुंजी के नाम से खोज सकते हैं, केवल त्रुटियां (HTTP 400 और उससे ऊपर) या केवल पुष्टि की प्रतीक्षा कर रहे कॉल (428 और उससे ऊपर) दिखा सकते हैं, और अवधि को पिछले एक घंटे, 24 घंटे या 7 दिनों तक सीमित कर सकते हैं। NexCMP नवीनतम 200,000 प्रविष्टियों को रखता है। किसी कुंजी के माध्यम से किए गए परिवर्तन ak:<admin>/<key name> नाम के तहत Logs › Admin actions में भी दिखाई देते हैं।

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

IP रेंज के भीतर किसी भी मशीन से रीड-ऑनली (read-only) की का परीक्षण करें:

curl -s https://cloud.example.com/v1/admin/agent/tools \
  -H "Authorization: Bearer ak_XXXX"

आपको अपने स्कोप द्वारा अनुमति प्राप्त टूल्स की एक JSON सूची मिलती है। एक चलाएँ:

curl -s -X POST https://cloud.example.com/v1/admin/agent/tools/system_health \
  -H "Authorization: Bearer ak_XXXX" \
  -H "Content-Type: application/json" -d '{}'

कुंजी का Last used समय बदल जाता है और कॉल Activity में दिखाई देता है। संपूर्ण टूल सूची और OpenAPI विवरण (/v1/admin/openapi.json) का वर्णन Connect an AI client में किया गया है।

Errors

त्रुटियाँ JSON हैं: {"error": {"code": "...", "message": "..."}}।

HTTP	code	अर्थ	सुधार
401	invalid_key	की गायब है, विकृत है या अज्ञात है। जब किसी गैर-एडमिन पथ पर ak_ की का उपयोग किया जाता है तब भी यह लौटता है।	की की जाँच करें; इसका उपयोग केवल /v1/admin/ और /mcp/admin पर करें।
401	key_expired	की की समाप्ति अवधि बीत चुकी है।	एक नई कुंजी बनाएँ।
401	key_revoked	की को रद्द कर दिया गया था।	एक नई कुंजी बनाएँ।
403	ip_not_allowed	कॉलर का IP की की IP रेंज से बाहर है।	अनुमत IP से कॉल करें, या सही रेंज वाली की बनाएँ।
403	local_only_key	AI Chat या सर्वर CLI के लिए बनाई गई की का उपयोग किसी अन्य मशीन से किया गया था।	ये की केवल पैनल सर्वर पर ही काम करती हैं।
403	insufficient_scope	की में स्कोप नहीं है; उत्तर में required_scope शामिल है।	उस स्कोप के साथ एक की बनाएँ।
403	forbidden_for_keys	एंडपॉइंट, या आपके द्वारा बदलने का प्रयास किया गया सेटिंग, की के लिए बंद है।	इसे एडमिन में करें।
403	demo_read_only	पैनल डेमो मोड में है और कॉल राइट करती है।	गैर-डेमो पैनल का उपयोग करें।
403	confirm_in_ui	इस कार्रवाई की पुष्टि एडमिन में स्क्रीन पर की जानी चाहिए।	पुष्टि कार्ड को स्वीकृत करें।
428	confirm_required	पूर्वावलोकन तैयार है; कुछ भी बदला नहीं है। इसमें confirm_token शामिल है।	पूर्वावलोकन दिखाएँ, फिर X-Confirm-Token के साथ दोहराएँ।
409	confirm_expired	टोकन 5 मिनट से अधिक पुराना है।	नए पूर्वावलोकन के लिए अनुरोध पुनः भेजें।
409	confirm_mismatch	टोकन एक अलग अनुरोध का है (विधि, पथ या बॉडी भिन्न है)।	समान अनुरोध को दोहराएँ।
409	confirm_invalid	अज्ञात या पहले से उपयोग किया गया टोकन।	नए पूर्वावलोकन के लिए अनुरोध पुनः भेजें।
429	rate_limited	इस मिनट बहुत अधिक कॉल हो गईं।	Retry-After की प्रतीक्षा करें।
400	invalid_path	पथ में वर्जित अनुक्रम शामिल हैं।	एक सादे पथ का उपयोग करें।
413	too_large	बॉडी 10 MB से अधिक है।	कम डेटा भेजें।
400	invalid_argument	टूल का तर्क गायब है, अज्ञात है या उसका प्रकार गलत है; संदेश इसका नाम बताता है।	तर्क को ठीक करें।

Limits & notes

• की को कम समय तक चलने वाली और सीमित रखें। प्रति क्लाइंट एक की को प्राथमिकता दें ताकि आप एक अकेली की को रद्द कर सकें।
• एक कुंजी उतनी ही शक्तिशाली होती है जितने उसके स्कोप होते हैं। secrets:write के साथ billing:write सबसे संवेदनशील संयोजन है; धन संबंधी कार्रवाइयां अभी भी पूर्वावलोकन (preview) पर रुक जाती हैं।
• स्वचालित रूप से बनाई गई की (AI Chat, सर्वर CLI के लिए) केवल कुछ मिनटों के लिए जीवित रहती हैं और केवल पैनल सर्वर से काम करती हैं।
• किसी AI क्लाइंट को तुरंत बंद करने के लिए, उसकी कुंजी रद्द कर दें। OAuth कनेक्शन Connected apps टैब (OAuth connectors) पर रद्द किए जाते हैं।