# API Keys और Developer Access

Source: https://support.kapsulehost.com/hi-in/developer-api-access

KapsuleHost आपको दो डेवलपर सर्फेस देता है: आपके खाते को प्रोग्रामेटिक रूप से पढ़ने के लिए स्कोप्ड API कुंजियाँ, और एक रिमोट बिल्ड कैश जो आपकी अपनी मशीनों और CI रनर्स पर Turborepo और Nx बिल्ड को तेज़ करता है।

न तो डिफ़ॉल्ट रूप से सक्षम है। दोनों **Settings** से बनाए जाते हैं, और दोनों आपको एक गुप्त बिल्कुल एक बार देते हैं।

## API कुंजी बनाना

API कुंजियाँ **Settings** के अंदर, फिर **Security** के तहत, **API कुंजियाँ** कार्ड में रहती हैं।

![KPanel सुरक्षा सेटिंग्स में API कुंजियाँ कार्ड स्कोप चिप्स दिखाई दे रहे हैं](https://support.kapsulehost.com/help/screenshots/developer-api-access.8d15f634.webp)

1. **Settings** पर जाएँ, फिर **Security**।
2. **API कुंजियाँ** तक स्क्रॉल करें और **नई कुंजी** पर क्लिक करें।
3. कुंजी को एक नाम दें। फ़ील्ड "कुंजी का नाम (उदाहरण के लिए मेरी ऑटोमेशन स्क्रिप्ट)" सुझाता है। नाम केवल आपके लिए है, इसलिए इसे कहीं बताएँ कि कुंजी कहाँ उपयोग की जाएगी।
4. स्कोप चिप्स पर क्लिक करें यह चुनने के लिए कि कुंजी क्या कर सकती है। तीन रीड स्कोप पहले से चुने गए हैं: `read:sites`, `read:email`, और `read:domains`। इसे जोड़ने या हटाने के लिए एक चिप पर क्लिक करें।
5. **Create** पर क्लिक करें।

पूरी कुंजी एक बार दिखाई देती है, "अभी कॉपी करें" शीर्षक वाले हरे पैनल में। इसे सीधे अपने गुप्त स्टोर में कॉपी करें। जब आप उस पैनल को बंद करते हैं तो कुंजी चली जाती है: केवल एक छोटा उपसर्ग रखा जाता है, जो सब कुछ सूची कभी भी आपको फिर से दिखा सकती है।

> **Warning:** कुंजी दूसरी बार कभी प्रदर्शित नहीं होती है और इसे पुनर्प्राप्त नहीं किया जा सकता। यदि आप इसे खो देते हैं, तो उस कुंजी को रद्द करें और एक नई बनाएँ। इसे साझा दस्तावेज़, टिकट, कमिट या चैट संदेश में पेस्ट न करें।

केवल **Owner** और **Admin** भूमिकाएँ कुंजी बना सकती हैं। कोई अन्य भूमिका अनुमति त्रुटि प्राप्त करती है। जब कुंजी बनाई जाती है, तो एक सुरक्षा सतर्क ईमेल उस व्यक्ति के पते पर जाता है जिसने इसे बनाया था, इसलिए उनमें से एक अप्रत्याशित तत्काल जांचने लायक है।

## स्कोप्स

सात स्कोप्स दिए गए हैं:

| स्कोप | अनुदान देता है |
|---|---|
| `read:sites` | आपकी वेबसाइटें पढ़ना |
| `write:sites` | वेबसाइटों पर लेखन संचालन के लिए आरक्षित |
| `read:email` | आपके मेलबॉक्स पढ़ना |
| `write:email` | मेलबॉक्स पर लेखन संचालन के लिए आरक्षित |
| `read:domains` | आपके डोमेन पढ़ना |
| `write:domains` | डोमेन पर लेखन संचालन के लिए आरक्षित |
| `read:billing` | बिलिंग डेटा पढ़ने के लिए आरक्षित |

> **Note:** ग्राहक API आज केवल पढ़ने के लिए है। `write:` स्कोप्स और `read:billing` कुंजी पर चुने जा सकते हैं, लेकिन कोई ग्राहक अंतिम बिंदु वर्तमान में उनका उपभोग नहीं करता है, इसलिए उन्हें अनुदान देना कुछ नहीं बदलता। केवल रीड स्कोप्स अनुदान दें जिनकी आपको वास्तव में आवश्यकता है और लेखन अंतिम बिंदु भेजे जाने पर कुंजी पर फिर से जाएँ।

## कुंजी का उपयोग करना

`Authorization` हेडर पर वाहक टोकन के रूप में कुंजी भेजें।

```sh
curl https://kpanel.kapsulehost.com/api/v1/sites \
  -H "Authorization: Bearer YOUR_KEY_HERE"
```

तीन अंतिम बिंदु ग्राहक API कुंजी स्वीकार करते हैं:

| अंतिम बिंदु | आवश्यक स्कोप | रिटर्न करता है |
|---|---|---|
| `GET /api/v1/sites` | `read:sites` | आपकी वेबसाइटें, डोमेन, एप्लिकेशन प्रकार और स्थिति के साथ |
| `GET /api/v1/domains` | `read:domains` | आपके डोमेन, स्थिति और समाप्ति के साथ |
| `GET /api/v1/mailboxes` | `read:email` | आपके मेलबॉक्स |

कोई कुंजी, एक अज्ञात कुंजी, या रद्द की गई कुंजी वाला अनुरोध `401` रिटर्न करता है। सही स्कोप के बिना एक वैध कुंजी `403` रिटर्न करती है, आवश्यक स्कोप का नाम देते हुए एक संदेश के साथ। हर सफल कॉल कुंजी की अंतिम-उपयोग की गई टाइमस्टैम्प को अपडेट करता है।

> **Tip:** धीरे पोल करें। ये अंतिम बिंदु लाइव खाता डेटा पढ़ते हैं, और उनके विरुद्ध एक तंग लूप दुरुपयोग से अप्रभेद्य है। किसी भी चीज़ के लिए जो डैशबोर्ड को चाहिए उसके लिए एक बार एक मिनट उदार है; एक घंटा में एक बार आमतौर पर काफी है।

## कुंजियों की समीक्षा और रद्द करना

API कुंजियाँ तालिका प्रत्येक सक्रिय कुंजी को **Name**, **Prefix** (कुंजी की दृश्यमान शुरुआत), और **Scopes** द्वारा सूचीबद्ध करती है। इसे मारने के लिए एक पंक्ति के अंत में **Revoke** पर क्लिक करें।

> **Important:** रद्द करना तत्काल प्रभाव डालता है और कोई पुष्टि संवाद नहीं है। अगला अनुरोध उस कुंजी का उपयोग करके `401` के साथ विफल रहता है। एक रद्द की गई कुंजी को पुनर्स्थापित नहीं किया जा सकता है, इसलिए क्लिक करने से पहले सुनिश्चित करें कि आप जानते हैं कि यह क्या उपयोग कर रहा है।

कुंजियाँ **account** की हैं, उस व्यक्ति की नहीं जिसने उन्हें बनाया था। [टीम पृष्ठ](https://support.kapsulehost.com/hi-in/account-team-members) से एक साथी को हटाने से वह कुंजियाँ रद्द नहीं होती हैं जो उन्होंने बनाई हैं। अपने ऑफबोर्डिंग में एक कुंजी समीक्षा बनाएँ: व्यक्ति को हटाएँ, फिर यहाँ आएँ और कुछ भी रद्द करें जो उन्होंने बनाया है।

कुंजी निर्माण और रद्दीकरण दोनों [ऑडिट लॉग](https://support.kapsulehost.com/hi-in/account-audit-log) में `api_key.*` क्रियाओं के तहत रिकॉर्ड किए जाते हैं, अभिनेता और मूल IP पते के साथ।

## रिमोट बिल्ड कैश

**Developer** पृष्ठ, सेटिंग्स रेल के Advanced समूह में, **Remote Build Cache** प्रदान करता है। पैनल इसे "Turborepo और Nx बिल्ड को मशीनों और CI पाइपलाइनों में एक वितरित कैश साझा करके तेज़ करें" के रूप में वर्णित करता है।

1. **Settings** पर जाएँ, फिर **Developer**।
2. **Remote cache सक्षम करें** पर क्लिक करें।
3. "नया टोकन तैयार किया गया। इसे अभी कॉपी करें, यह फिर से नहीं दिखाया जाएगा" शीर्षक वाले पैनल से टोकन कॉपी करें।

फिर अपने CI कॉन्फ़िगरेशन या स्थानीय `.env.local` में दो पर्यावरण चर सेट करें:

```sh
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
```

टीम ID आपकी KapsuleHost खाता ID है, जो उसी पृष्ठ पर सेटअप निर्देशों में दिखाई देती है।

पृष्ठ अपनी अपनी संगतता बताता है: Turborepo 1.x और बाद में, Nx 16 और बाद में, और कोई भी उपकरण समान रिमोट कैश प्रोटोकॉल लागू करना। कलाकृतियाँ प्रति खाते संग्रहीत की जाती हैं और कभी भी खातों में साझा नहीं की जाती हैं।

दो अन्य नियंत्रण कार्ड पर बैठते हैं:

- **टोकन घुमाएँ** एक नया टोकन जारी करता है और पुरानी कुंजी को अमान्य करता है। कोई भी CI काम जो अभी भी पुरानी कुंजी को धारण कर रहा है कैश का उपयोग करना बंद कर देता है, इसलिए अपने रहस्यों के साथ घुमाएँ और अपडेट करें।
- **Disable** कैश को पूरी तरह से बंद कर देता है।

## दोनों के बीच चुनाव करना

वे असंबंधित समस्याओं को हल करते हैं और परस्पर विनिमेय नहीं हैं।

एक **API कुंजी** का उपयोग करें जब KapsuleHost के बाहर कुछ आपके खाते की स्थिति जानने की आवश्यकता है: एक स्थिति बोर्ड जो आपकी साइटों को सूचीबद्ध करता है, एक स्क्रिप्ट जो आपको शीघ्र ही समाप्त होने वाले डोमेन के बारे में चेतावनी देता है, एक सूची निर्यात।

**रिमोट बिल्ड कैश** का उपयोग करें जब आपका निर्माण धीमा है क्योंकि हर मशीन और हर CI रन अपरिवर्तित पैकेज को फिर से बनाता है। इसका आपकी होस्ट की गई साइटों से कोई संबंध नहीं है और आपके खाता डेटा को नहीं पढ़ता है।

## समस्या निवारण

**हर अनुरोध 401 रिटर्न करता है।** पुष्टि करें कि आपने हेडर को `Authorization: Bearer <key>` के रूप में एक एकल स्थान के साथ भेजा है, कि कुंजी को कॉपी करते समय छोटा नहीं किया गया था, और कि इसे रद्द नहीं किया गया है। आपकी कुंजी की शुरुआत को **Prefix** कॉलम के साथ तुलना करें यह सुनिश्चित करने के लिए कि आप उस कुंजी का उपयोग कर रहे हैं जो आप सोचते हैं।

**एक अनुरोध 403 एक स्कोप का नाम देते हुए रिटर्न करता है।** कुंजी में वह स्कोप नहीं है। स्कोप्स कुंजी बनाए जाने के समय निर्धारित होते हैं, इसलिए सही स्कोप्स के साथ एक प्रतिस्थापन बनाएँ और पुरानी को रद्द करें।

**मुझे API कुंजियाँ कार्ड नहीं दिखाई दे रहा है।** यह सुरक्षा पृष्ठ पर है, डेवलपर पृष्ठ पर नहीं। डेवलपर पृष्ठ केवल बिल्ड कैश रखता है।

**नई कुंजी बटन कुछ नहीं करता है।** आपकी भूमिका Admin से नीचे है। Owner या Admin से पूछें।

**बिल्ड कैश को हिट नहीं कर रहे हैं।** पुष्टि करें कि `TURBO_TOKEN` और `TURBO_TEAM` दोनों बिल्ड पर्यावरण में मौजूद हैं, कि टोकन को घुमाया नहीं गया है क्योंकि आपने इसे सेट किया था, और पृष्ठ अभी भी **Active** बैज दिखाता है।

**एक कुंजी जो मैंने नहीं बनाई है दिखाई दी।** इसे एक समझौते के रूप में मानें। इसे रद्द करें, फिर [Account Security](https://support.kapsulehost.com/hi-in/account-security) के माध्यम से काम करें और [ऑडिट लॉग](https://support.kapsulehost.com/hi-in/account-audit-log) की जाँच करें कि और क्या बदला गया।