खाता
API कुंजियाँ और डेवलपर पहुंच
Kapsule gives you two developer surfaces: scoped API keys for reading your account programmatically, and a remote build cache that speeds up Turborepo and Nx builds on your own machines and CI…
API Keys और Developer Access
Kapsule आपको दो developer surfaces प्रदान करता है: अपने account को programmatically पढ़ने के लिए scoped API keys, और एक remote build cache जो आपकी अपनी machines और CI runners पर Turborepo और Nx builds को तेज करता है।
न तो default रूप से enabled है। दोनों Settings से बनाए जाते हैं, और दोनों आपको एक secret बिल्कुल एक बार देते हैं।
API Key बनाना
API keys Settings के अंतर्गत, फिर Security में, API Keys card में रहते हैं।
- Settings पर जाएं, फिर Security पर जाएं।
- API Keys तक scroll करें और New key पर क्लिक करें।
- Key को एक नाम दें। यह field सुझाता है "Key name (e.g. My automation script)"। नाम केवल आपके लिए है, इसलिए इसे बताएं कि key कहां उपयोग किया जाएगा।
- scope chips पर क्लिक करें यह चुनने के लिए कि key क्या कर सकता है। तीन read scopes पहले से चुने गए हैं:
read:sites,read:email, औरread:domains। chip को जोड़ने या हटाने के लिए उस पर क्लिक करें। - Create पर क्लिक करें।
पूरी key एक बार दिखाई देती है, एक हरे panel में जिसका शीर्षक "Copy now" है। इसे तुरंत अपने secret store में कॉपी करें। जब आप उस panel को dismiss करते हैं तो key चली जाती है: केवल एक छोटा prefix रखा जाता है, जो सब कुछ है जो list कभी आपको फिर से दिखा सकता है।
key कभी दूसरी बार display नहीं होती है और recover नहीं की जा सकती। अगर आप इसे खो देते हैं, तो उस key को revoke करें और एक नई बनाएं। इसे shared document, ticket, commit, या chat message में paste न करें।
केवल Owner और Admin roles एक key बना सकते हैं। कोई भी अन्य role को permissions error मिलता है। जब एक key बनाया जाता है, तो एक security alert email उस व्यक्ति के address पर जाता है जिसने इसे बनाया है, इसलिए एक अप्रत्याशित email की तुरंत जांच के लायक है।
Scopes
सात scopes की पेशकश की जाती है:
| Scope | Grants |
|---|---|
read:sites | अपनी websites को पढ़ना |
write:sites | websites पर write operations के लिए आरक्षित |
read:email | अपने mailboxes को पढ़ना |
write:email | mailboxes पर write operations के लिए आरक्षित |
read:domains | अपने domains को पढ़ना |
write:domains | domains पर write operations के लिए आरक्षित |
read:billing | billing data को पढ़ने के लिए आरक्षित |
customer API आज read-only है। write: scopes और read:billing को एक key पर चुना जा सकता है, लेकिन कोई भी customer endpoint फिलहाल उन्हें consume नहीं करता है, इसलिए उन्हें grant करने से कुछ नहीं बदलता। केवल उन read scopes को grant करें जिनकी आपको वास्तव में आवश्यकता है और जब write endpoints ship हों तो key को फिर से देखें।
Key का उपयोग करना
key को Authorization header पर एक bearer token के रूप में भेजें।
curl https://kpanel.kapsulehost.com/api/v1/sites \
-H "Authorization: Bearer YOUR_KEY_HERE"
तीन endpoints एक customer API key स्वीकार करते हैं:
| Endpoint | Scope required | Returns |
|---|---|---|
GET /api/v1/sites | read:sites | आपकी websites, domain, application type और status के साथ |
GET /api/v1/domains | read:domains | आपके domains, status और expiry के साथ |
GET /api/v1/mailboxes | read:email | आपके mailboxes |
एक request जिसमें कोई key नहीं है, एक unknown key है, या एक revoked key है, 401 return करता है। सही scope के बिना एक valid key, 403 return करता है जिसमें एक message है जो उस scope का नाम देता है जिसकी आवश्यकता थी। प्रत्येक successful call key के last-used timestamp को update करता है।
gently poll करें। ये endpoints live account data पढ़ते हैं, और उनके विरुद्ध एक tight loop abuse से अलग नहीं है। एक बार प्रति मिनट कुछ भी उदार है जो एक dashboard को चाहिए; एक बार प्रति घंटा आमतौर पर काफी है।
Keys की समीक्षा और Revoking
API Keys table प्रत्येक active key को Name, Prefix (key की दिखाई देने वाली शुरुआत), और Scopes के आधार पर सूचीबद्ध करता है। एक row के अंत में Revoke पर क्लिक करके इसे kill करें।
Revoking तुरंत प्रभावी होता है और कोई confirmation dialog नहीं है। उस key का उपयोग करने वाली अगली request 401 के साथ fail हो जाती है। एक revoked key को restore नहीं किया जा सकता है, इसलिए सुनिश्चित करें कि आप जानते हैं कि इसे क्लिक करने से पहले क्या उपयोग कर रहा है।
Keys account से संबंधित हैं, उस व्यक्ति से नहीं जिसने उन्हें बनाया। Team page से एक teammate को हटाने से उनके द्वारा बनाई गई keys revoke नहीं होती हैं। अपनी offboarding में एक key review बनाएं: व्यक्ति को हटाएं, फिर यहां आएं और कुछ भी revoke करें जो उन्होंने बनाया है।
Key creation और revocation दोनों audit log में api_key.* actions के तहत recorded हैं, actor और originating IP address के साथ।
Remote Build Cache
Developer page, settings rail के Advanced group में, एक Remote Build Cache प्रदान करता है। panel इसे "Turborepo और Nx builds को accelerate करने के एक तरीके के रूप में वर्णित करता है machines और CI pipelines के बीच एक distributed cache साझा करके।"
- Settings पर जाएं, फिर Developer पर जाएं।
- Enable remote cache पर क्लिक करें।
- "New token generated. Copy it now, it won't be shown again" शीर्षक वाले panel से token कॉपी करें।
फिर अपने CI configuration या local .env.local में दो environment variables सेट करें:
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
team ID आपकी Kapsule account ID है, जो उसी page पर setup instructions में दिखाई देता है।
page अपनी स्वयं की compatibility बताता है: Turborepo 1.x और बाद में, Nx 16 और बाद में, और कोई भी tool जो समान remote cache protocol को implement करता है। Artifacts को प्रति account stored किया जाता है और कभी accounts के बीच shared नहीं किया जाता है।
card पर दो और controls बैठते हैं:
- Rotate token एक नया token जारी करता है और पुराने को invalidate करता है। कोई भी CI job जो अभी भी पुराने token को रखता है cache का उपयोग करना बंद कर देता है, इसलिए अपने secrets के साथ rotate और update करें।
- Disable cache को पूरी तरह से बंद कर देता है।
दोनों के बीच चुनाव
वे असंबंधित समस्याओं को हल करते हैं और परस्पर विनिमेय नहीं हैं।
एक API key का उपयोग करें जब कुछ Kapsule के बाहर को आपके account की स्थिति जानने की आवश्यकता है: एक status board जो आपकी sites को list करता है, एक script जो आपको expiring domains के बारे में चेतावनी देता है, एक inventory export।
remote build cache का उपयोग करें जब आपकी builds धीमी हैं क्योंकि हर machine और हर CI run एक ही unchanged packages को rebuild करते हैं। इसका आपकी hosted sites से कोई लेना देना नहीं है और आपके account data को नहीं पढ़ता है।
यदि आप API को कॉल करने के बजाय Git से deploy कर रहे हैं, तो Kapsule Orbit को देखें। यह आपकी repository से सीधे build और ship करता है, build caching आपके लिए handled के साथ।
समस्या निवारण
हर request 401 return करता है। पुष्टि करें कि आपने header को Authorization: Bearer <key> के रूप में एक single space के साथ भेजा है, कि key को copy करते समय truncate नहीं किया गया था, और कि इसे revoke नहीं किया गया है। अपनी key की शुरुआत को Prefix column के साथ compare करें यह सुनिश्चित करने के लिए कि आप उस key का उपयोग कर रहे हैं जो आप सोचते हैं कि आप कर रहे हैं।
एक request 403 return करता है जो एक scope का नाम बताता है। key में वह scope नहीं है। Scopes को तब fixed किया जाता है जब key बनाया जाता है, इसलिए सही scopes के साथ एक replacement बनाएं और पुरानी को revoke करें।
मैं API Keys card नहीं देख सकता। यह Security page पर है, Developer page पर नहीं। Developer page केवल build cache को hold करता है।
New key button कुछ नहीं करता। आपकी role Admin से नीचे है। Owner या एक Admin से पूछें।
Builds cache को hit नहीं कर रहे हैं। Check करें कि TURBO_TOKEN और TURBO_TEAM दोनों build environment में मौजूद हैं, कि token को तब से rotate नहीं किया गया है जब आपने इसे सेट किया था, और कि page अभी भी Active badge दिखाता है।
एक key जो मैंने बनाया नहीं दिखाई दिया। इसे एक compromise के रूप में treat करें। इसे revoke करें, फिर Account Security के माध्यम से काम करें और audit log को check करें कि और क्या बदला।