API keys और scopes

पोर्टल में कहाँ: API keys (/api-keys)। एडमिन में कहाँ: Customers › Customers › API keys (/customers/apikeys)।

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

एक API key किसी स्क्रिप्ट, CI जॉब, cmp CLI या AI सहायक (MCP) को केवल दी गई अनुमतियों (scopes) के साथ, किसी ग्राहक की ओर से REST API कॉल करने की अनुमति देती है। ग्राहक कुंजियाँ vk_ से शुरू होती हैं। वे सेवाएँ पढ़ और प्रबंधित कर सकती हैं लेकिन कभी भी पैसे या खाते को नहीं छू सकतीं।

आवश्यकताएं

आइटम	आवश्यकता
ग्राहक	एक साइन-इन किया गया पोर्टल सत्र (कोई कुंजी अन्य कुंजियाँ बना या संपादित नहीं कर सकती, और ग्राहक का प्रतिरूपण करने वाला प्रशासक भी नहीं कर सकता)।
स्विच	API कुंजियाँ डिफ़ॉल्ट रूप से चालू होती हैं। यदि वे बंद हैं, तो कॉल्स 401 api_keys_disabled उत्तर देती हैं।
डिपेंडेंसी	किसी उत्पाद के स्कोप केवल तभी दिखाई देते हैं जब वह उत्पाद साइट पर सक्षम हो।

कुंजी बनाएँ (ग्राहक)

1. पोर्टल में साइन इन करें और API keys खोलें।

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

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

   फ़ील्ड	Rule
   Key name	आवश्यक, 60 वर्णों तक ("deploy server", "backup script")।
   यह key क्या कर सकती है	अपनी ज़रूरत के स्कोप पर टिक करें — कम से कम एक। केवल-पढ़ने वाली (read-only) कुंजी को कोई लिखने का स्कोप नहीं मिलना चाहिए। उन स्कोप के प्रति सावधान रहें जिन पर पैसे खर्च होते हैं या जो डेटा हटाते हैं।
   Expiry	कभी नहीं, 30 दिन, 90 दिन या 1 वर्ष (API 1 से 3650 दिनों को स्वीकार करता है)।
   केवल इन IP से calls की अनुमति दें	प्रति पंक्ति एक IP या CIDR रेंज, 20 तक (IPv4 या IPv6)। खाली का अर्थ है कोई भी IP। जब भी संभव हो अपने सर्वर के IP को पिन करें।

4. फ़ॉर्म की पुष्टि करें। कुंजी एक विंडो में एक बार दिखाई जाती है "Key created — shown ONCE"। इसे कॉपी करें और I saved the key पर क्लिक करें। केवल एक SHA-256 हैश संग्रहीत किया जाता है, इसलिए एक प्रशासक भी इसे दोबारा नहीं पढ़ सकता; यदि आप इसे खो देते हैं, तो इसे निरस्त करें और एक नई बनाएँ।

5. पोर्टल कुंजी का परीक्षण करने के लिए एक तैयार curl कमांड भी दिखाता है।

एक कुंजी vk_ जैसी दिखती है जिसके बाद एक लंबा रैंडम स्ट्रिंग होता है। सूची केवल पहले वर्ण (उदाहरण के लिए vk_a1b2c3d4), स्कोप, समाप्ति, अंतिम उपयोग, अनुरोध संख्या और स्थिति (Active, Expired, Revoked) दिखाती है।

संपादित करें, निरस्त करें, ऑडिट करें

• Edit से नाम, स्कोप्स, अनुमति प्राप्त IP और समाप्ति तिथि बदली जा सकती है। यह इंपरसोनेटेड सेशन के दौरान अनुमति नहीं है।
• Revoke की तुरंत बंद हो जाती है और इसे पूर्ववत नहीं किया जा सकता। इसका उपयोग लॉग उपलब्ध रखने के लिए पंक्ति को सुरक्षित रखा जाता है।
• Key usage log पिछले 60 दिनों के राइट कमांड और हर त्रुटि को दिखाता है: समय, अनुरोध, की, परिणाम और स्रोत IP।
• डिफ़ॉल्ट रूप से एक खाते में अधिकतम 10 सक्रिय की हो सकती हैं।
• CLI या MCP लॉगिन के माध्यम से बनाई गई की Connected apps & devices के अंतर्गत दिखाई देती हैं और उन्हें वहीं रद्द (revoked) किया जा सकता है।

Scopes

स्कोप के नाम area:action फ़ॉर्म में होते हैं। कौन से विकल्प उपलब्ध हैं, यह आपके द्वारा सक्षम किए गए उत्पादों पर निर्भर करता है।

Scope	Allows
catalog:read	प्लान और कैटलॉग पढ़ें।
vm:read	VM, मेट्रिक्स और VM चालान पढ़ें।
vm:write	पावर एक्शन, मामूली बदलाव, फ़ायरवॉल, त्वरित स्नैपशॉट।
vm:create	VM बनाएँ (पैसा खर्च होता है)।
vm:plan	प्लान बदलें या साइज़ बदलें (पैसा खर्च होता है)।
vm:destroy	VM हटाएँ।
vm:restore	स्नैपशॉट से VM रीस्टोर करें (डिस्क ओवरराइट हो जाती है)।
vm:console	VNC कंसोल टिकट खोलें।
sshkey:read, sshkey:write	SSH की पढ़ें, जोड़ें और हटाएँ।
volume:read, volume:write, volume:create, volume:destroy	डेटा वॉल्यूम (बनाने और बड़ा करने में पैसे लगते हैं; नष्ट करने पर डेटा खो जाता है)।
backup:read, backup:write, backup:restore	Backups (रीस्टोर करने पर डिस्क ओवरराइट हो जाती है)।
billing:read	वॉलेट, चालान, भुगतान इतिहास — केवल पढ़ने के लिए।
bandwidth:buy	बैंडविड्थ ऐड-ऑन खरीदें (पैसा खर्च होता है)।
account:read, account:write	प्रोफाइल, ओवरव्यू, गतिविधि, सूचनाएं; account:write केवल सूचनाओं को पढ़े के रूप में चिह्नित करता है।
apikey:read	खाते की की और उपयोग लॉग की सूची दिखाएं (बना, संपादित या रद्द नहीं कर सकते)।
apikey:self	प्रत्येक की पर निहित: कॉलिंग की (GET /v1/apikeys/self) का निरीक्षण करें।
ticket:read, ticket:write	सहायता टिकट।
aff:read, transfer:read	एफ़िलिएट प्रोग्राम और सर्विस ट्रांसफर — केवल पढ़ने के लिए।
k8s:read, k8s:write, k8s:create, k8s:scale, k8s:destroy, k8s:kubeconfig	Kubernetes (बनाने और स्केल करने में पैसे लगते हैं; kubeconfig क्लस्टर-एडमिन है)।
vpc:read, vpc:write, vpc:create, vpc:destroy	Private Cloud.
image:read, image:write	OS और ISO इमेज (स्टोर करने पर प्रति घंटे बिल बनता है)।
s3:read, s3:write, s3:create, s3:destroy, s3:keys	Object Storage (S3 सीक्रेट एक बार दिखाया जाता है)।
vpn:read, vpn:detail, vpn:write, vpn:create, vpn:destroy	VPN और IPv6 प्रॉक्सी (कनेक्शन विवरण में प्रॉक्सी पासवर्ड शामिल हैं)।
dedicated:read, dedicated:write, dedicated:console, dedicated:create, dedicated:destroy	Dedicated servers (वॉलेट से ऑर्डर बनाएं; नष्ट करने पर OS रीइंस्टॉल हो जाता है)।
shield:read, shield:write, shield:agent	DDoS Shield, केवल तभी जब वह मॉड्यूल सक्षम हो।

की के स्कोप के बाहर की कॉल 403 scope_required उत्तर देती है; ऐसा पथ जिसे कोई की कॉल नहीं कर सकती, 403 endpoint_not_public उत्तर देती है।

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

कोई भी स्कोप ये काम नहीं खोल सकता: पैसे जोड़ना या निकालना, कार्ड या ऑटो टॉप-अप बदलना, पासवर्ड, ई-मेल या 2FA बदलना, खाता हटाना, अन्य की बनाना, संपादित करना या रद्द करना। इनके लिए हमेशा साइन-इन किए गए ब्राउज़र की आवश्यकता होती है। यहाँ तक कि लीक हुई की भी ग्राहक के पैसे या खाते को नहीं छू सकती।

वे नियम जिन पर आप भरोसा कर सकते हैं

Rule	Detail
Site-bound	एक की केवल उसी साइट (डोमेन) पर काम करती है जहाँ इसे बनाया गया था।
Rate limits	प्रति की और प्रति खाता: डिफ़ॉल्ट रूप से 120 और 300 अनुरोध प्रति मिनट।
Idempotency	वे ऑपरेशन जिनमें पैसे खर्च होते हैं या जिन्हें दोहराया नहीं जा सकता, उनके लिए Idempotency-Key हेडर की आवश्यकता होती है।
कोटा	एक की ग्राहक के समान quotas के अधीन है।
Locked account	लॉक किए गए ग्राहक की कुंजियाँ काम करना बंद कर देती हैं (403 account_blocked)।
Audit	प्रशासक द्वारा निरस्तीकरण को एडमिन ऑडिट लॉग में लिखा जाता है।

प्रशासक दृश्य

1. Customers › API keys खोलें (/customers/apikeys)। तालिका में कुंजी का नाम और शुरुआती अक्षर, स्वामी, स्कोप, स्थिति, अंतिम उपयोग (समय, अनुरोध संख्या, IP), और समाप्ति तिथि दिखाई देती है।
2. यदि आपके पास रीसेलर्स हैं तो साइट के अनुसार फ़िल्टर करें। नाम, ID या कुंजी की शुरुआत से खोजें।
3. सक्रिय कुंजी को रोकने के लिए Revoke पर क्लिक करें, या उसके उपयोग के लिए Log पर क्लिक करें।
4. प्रशासक कुंजियों को देख और निरस्त कर सकते हैं लेकिन ग्राहकों के लिए उन्हें पढ़ या बना नहीं सकते।

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

1. केवल vm:read स्कोप के साथ एक कुंजी बनाएँ।
2. curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX" VM सूची लौटाता है।
3. curl -s -X POST .../v1/vm/<id>/start -H "Authorization: Bearer vk_XXXX" 403 scope_required उत्तर देता है।
4. कुंजी को निरस्त करें; पहली कॉल अब 401 key_revoked उत्तर देती है।

Limits & notes

• कुंजी को फिर कभी नहीं दिखाया जाता है। इसे पासवर्ड की तरह मानें और सीक्रेट मैनेजर या CI सीक्रेट में सहेजें।
• प्रति स्क्रिप्ट एक कुंजी, न्यूनतम स्कोप, कम समाप्ति अवधि और एक IP अनुमति सूची को प्राथमिकता दें; नई कुंजी बनाकर और पुरानी को निरस्त करके रोटेट करें।
• डिवाइस लॉगिन (CLI, MCP) से मिलने वाली कुंजियाँ डिफ़ॉल्ट रूप से 90 दिनों की होती हैं।
• हटाई गई या स्थानांतरित की गई संसाधन कुंजियाँ निरस्त होने से प्रभावित नहीं होती हैं।

ट्रबलशूटिंग

लक्षण	कारण	सुधार
त्रुटि too_many_keys (422)	सक्रिय कुंजियों की सीमा (डिफ़ॉल्ट रूप से 10) पूरी हो गई है	पुरानी कुंजी को निरस्त करें।
त्रुटि invalid_argument: कोई स्कोप नहीं चुना गया	कोई स्कोप टिक नहीं किया गया है	कम से कम एक स्कोप पर टिक करें।
अनुमत IP पर त्रुटि invalid_argument	कोई प्रविष्टि IP या रेंज नहीं है, गलत उपसर्ग लंबाई है, या 20 से अधिक प्रविष्टियाँ हैं	प्रति पंक्ति एक IP या CIDR, उदाहरण के लिए 203.0.113.0/24।
इम्पर्सनेशन के दौरान निर्माण अस्वीकार कर दिया जाता है	impersonate_forbidden	ग्राहक से कुंजी बनाने के लिए कहें।
401 key_expired	समाप्ति तिथि बीत चुकी है	एक नई कुंजी बनाएँ।
401 key_ip_denied	कॉल करने वाले का IP अनुमति सूची में नहीं है	IP जोड़ें या सूची साफ़ करें।
401 api_keys_disabled	सुविधा बंद है	अपने प्रशासक से पूछें (api_keys_enabled सेटिंग)।