API keys और एक्सेस टोकन

API key वह तरीका है जिससे आपके प्रोग्राम LinkHarbor API तक पहुँचते हैं। यह किसी व्यक्ति की नहीं, एक वर्कस्पेस की होती है, और ठीक वही कर सकती है जिसकी आप स्कोप से अनुमति देते हैं। असली कॉल के लिए आप key के बदले एक कम समय वाला access token लेते हैं।

#API keys कौन बना सकता है?

• वर्कस्पेस के मालिक और एडमिन – एडिटर और दर्शकों को “Callback और API” के तहत सिर्फ़ “कनेक्ट किए गए ऐप” कार्ड दिखता है
• Creator Pro से; Creator Free में कार्ड पर “API keys Creator Pro से उपलब्ध हैं।” लिखा होता है
• एक साथ सक्रिय: Creator Pro में 5 तक, Creator Agency में 20 तक, Enterprise में 50 तक keys

सीमा पूरी होने पर key बनाना 409 limit_reached के साथ विफल होता है। पहले कोई ऐसी key हटाएँ जिसकी अब ज़रूरत नहीं है।

#API key बनाएँ

1. नेविगेशन में “Callback और API” खोलें
2. “API keys” कार्ड में “+ नई key बनाएँ” पर क्लिक करें
3. “नाम (वैकल्पिक)” के तहत एक नाम डालें, जिससे आप बाद में key पहचान सकें, जैसे “CI/CD Pipeline” या “शॉप सिंक”
4. “स्कोप” के तहत हर हिस्से के लिए “पढ़ना” या “लिखना” चुनें
5. “key बनाएँ” पर क्लिक करें
6. “Key secret (निजी)” तुरंत कॉपी करें और किसी सुरक्षित जगह रखें
7. डायलॉग बंद करें – key ID आपको सूची में कभी भी मिल जाती है

“नाम (वैकल्पिक)”

ज़्यादा से ज़्यादा 64 अक्षर। नाम के बिना key सूची में “API key #ID” के रूप में दिखती है।

“स्कोप”

कम से कम एक ज़रूरी है। “लिखना” उसी हिस्से के लिए “पढ़ना” अपने आप शामिल करता है। आँकड़े और समर्थकों के भुगतान सिर्फ़ पढ़ने के लिए हैं, वर्कस्पेस टेम्पलेट सिर्फ़ लिखने के लिए। सभी स्कोप स्कोप विस्तार से में समझाए गए हैं।

“Key secret (निजी)”

lt_ से शुरू होता है और ठीक एक बार दिखाया जाता है (“⚠️ सिर्फ़ एक बार दिखेगी — अभी कॉपी करें!”)। LinkHarbor इसका सिर्फ़ एक हैश सहेजता है और बाद में इसे आपको फिर नहीं दिखा सकता।

“Key ID:”

अंकों और बड़े अक्षरों A–F से बने 16 अक्षर, जैसे 6F668EA6598B0692। यह गुप्त नहीं है और सूची में कॉपी बटन के साथ दिखती है।

#Key की सूची

हर सक्रिय key अपना नाम, “सक्रिय” स्थिति, key ID, अपने स्कोप, “बनाई गई:” और “आख़िरी इस्तेमाल:” या “अभी इस्तेमाल नहीं हुई” दिखाती है। आख़िरी इस्तेमाल का समय key से हर कॉल पर अपडेट होता है, ज़्यादा से ज़्यादा मिनट में एक बार। “↺ रीफ़्रेश करें” सूची फिर से लोड करता है।

#Key के बदले access token लें

curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'

{ "token": "eyJhbGciOiJIUzI1NiIs…", "expires_in": 900 }

token

Access token। इसे आप हर अनुरोध के साथ Authorization: Bearer <token> के रूप में भेजते हैं।

expires_in

सेकंड में वैधता: 900, यानी 15 मिनट। कोई refresh token नहीं है – अवधि ख़त्म होने पर बस key ID और secret से नया टोकन लें।

टोकन वर्कस्पेस का प्रतिनिधित्व करता है और ठीक key के स्कोप रखता है। किसी व्यक्ति की तरह इसकी कोई भूमिका नहीं होती: जिन एंडपॉइंट को डैशबोर्ड मालिकों और एडमिन के लिए रखता है (सदस्य, बिलिंग, डोमेन मैनेज करना, webhooks, वर्कस्पेस सेटिंग), वे API keys के टोकन के लिए हमेशा मना होते हैं। अपवाद शॉर्ट लिंक और वर्कस्पेस टेम्पलेट हैं, जो संबंधित स्कोप के साथ काम करते हैं, और read:workspaces के साथ callback secrets पढ़ना (सादे टेक्स्ट वाले secret के बिना)।

#असफल कोशिशें और लॉक

api_key_locked में बचा हुआ समय details.retry_after_sec में होता है। एक सफल बदलाव काउंटर रीसेट कर देता है।

#Key हटाएँ और बदलें

1. key के बगल में “हटाएँ” पर क्लिक करें
2. पुष्टि के लिए DELETE टाइप करें
3. “हमेशा के लिए हटाएँ” पर क्लिक करें

key तुरंत काम करना बंद कर देती है – पहले जारी हुए access token भी उसी पल से काम करना बंद कर देते हैं और 401 invalid_token पाते हैं। कोई rotate बटन नहीं है। key बदलने के लिए एक नई key बनाएँ, अपने प्रोग्राम को उस पर ले जाएँ और फिर पुरानी हटाएँ।

#जब प्लान घटता है

अगर वर्कस्पेस Creator Free पर आता है, तो सभी API keys रद्द हो जाती हैं। अगर वह कम keys वाले प्लान पर जाता है, तो सबसे नई बनी रहती हैं और बाकी रद्द हो जाती हैं। रद्द की गई keys बाद में अपग्रेड करने पर वापस नहीं आतीं – तब आप नई बनाते हैं। मालिकों को बंद हुए फ़ीचर की सूची के साथ एक ईमेल मिलता है। ज़्यादा जानकारी रद्द करना और डाउनग्रेड में।

#सुरक्षित रखना

• secret सिर्फ़ किसी secrets manager या environment variables में रखें, कभी सोर्स कोड या Git रिपॉज़िटरी में नहीं
• इसे कभी ऐसे कोड में इस्तेमाल न करें जो ब्राउज़र में या यूज़र के डिवाइस पर किसी ऐप में चलता है
• हर ऐप्लिकेशन के लिए अलग key बनाएँ, जितने हो सके उतने कम स्कोप के साथ
• जिन keys की अब ज़रूरत नहीं, उन्हें तुरंत हटाएँ
• लीक का शक होने पर: key हटाएँ और एक नई बनाएँ