Space Access Token

Space Access Token एक ऐसा टोकन है जिससे किसी एक Space के भीतर कंटेंट पढ़ा और लिखा जा सकता है। CMA से कंटेंट बनाया, संपादित और हटाया जा सकता है, और CDA रीड तथा Upload भी इसी टोकन से कॉल किए जाते हैं। जारी करते समय इसे एक SpaceRole से बाइंड किया जाता है, और वही भूमिका तय करती है कि टोकन क्या और कहाँ तक कर सकता है (किस Content Type को किस क्रिया से संभाल सकता है)।

केवल-पढ़ने वाली Delivery Access Token के विपरीत यह टोकन लिखने तक की अनुमति देता है। दूसरी ओर, पूरे उपयोगकर्ता खाते से बंधी Personal Access Token के विपरीत यह केवल एक Space तक सीमित रहता है, और Space सेटिंग, संगठन व खाते के तल या किसी दूसरी Space तक इसकी पहुँच नहीं होती। CMA में Space Access Token एक Space की उप-संसाधन है, और इसका पाथ /spaces/{spaceId}/space-access-tokens पर आधारित है। इस टोकन को सर्वर में रखना है या किसी उजागर क्लाइंट (जैसे अनाम पोस्टिंग) में, यह सेवा के अनुसार तय किया जाता है। यह लिखने के अधिकार वाला ताकतवर टोकन है, इसलिए बाइंड की जाने वाली भूमिका को उस जगह के उजागर दायरे के अनुसार सीमित करके सुरक्षा सुनिश्चित की जाती है जहाँ वह टोकन रखा जाता है (नीचे सुरक्षा: उजागर दायरे के अनुसार भूमिका बाइंडिंग देखें)।

संसाधन संरचना

नीचे Space Access Token बनाने पर मिलने वाली प्रतिक्रिया दी गई है। sys (सिस्टम गुण) में टोकन मान और दायरा होता है, और बॉडी में name, description तथा allowedReferrers होते हैं।

{
  "sys": {
    "id": "7WpR4mKq2bTnXfLc8Vd3HsJ9gEyAo",
    "type": "SpaceAccessToken",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "user": { "sys": { "id": "3trmXRLdJIqc9GPBbyFYQQwYT32LnU", "type": "Refer", "targetType": "User" } },
    "createdBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-19T02:15:38.472Z",
    "updatedBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-19T02:15:38.472Z",
    "accessToken": "SPCATq8Lm2vK9pXfR1Zt0Nc4Wd6Hg5Ua2Ee9Ck3PoYx8Bj6Hg5Ua2Ee9Ck3Po…",
    "scopes": ["SPACE_ACCESS_TOKEN"]
  },
  "allowedReferrers": [],
  "description": "कपड़ों की दुकान के शॉपिंग मॉल में उत्पाद दर्ज व संपादित करने के लिए सर्वर टोकन",
  "name": "उत्पाद बैकएंड सर्वर"
}

मुख्य कुंजियाँ:

• sys.id: Space Access Token का विशिष्ट पहचानकर्ता। एकल पुनर्प्राप्ति, संपादन और हटाने के पाथ के {spaceAccessTokenId} में जाता है।
• sys.space: वह Space जिससे यह टोकन संबद्ध है। टोकन केवल इसी एक Space में काम करता है।
• sys.accessToken: API कॉल में उपयोग किया जाने वाला गुप्त टोकन मान। यह SPCAT से शुरू होता है, और जारी करने के बाद पुनर्प्राप्ति में भी यही मान ज्यों का त्यों आता है, इसलिए उजागर होने को लेकर सावधानी बरतनी चाहिए (नीचे सुरक्षा अनुभाग देखें)।
• sys.scopes: टोकन का अनुमति दायरा। Space Access Token जारी करते समय हमेशा ["SPACE_ACCESS_TOKEN"] होता है।
• sys.user: इस टोकन का अधिकार-धारक समर्पित उपयोगकर्ता। जारी करते समय स्वतः बन जाता है, और बाइंड की गई SpaceRole के अधिकार इसी उपयोगकर्ता को दिए जाते हैं। यानी टोकन का प्रभावी अधिकार इसी उपयोगकर्ता से आता है। यह उस व्यक्ति (sys.createdBy) से भिन्न उपयोगकर्ता है जिसने इस टोकन को वास्तव में जारी किया।
• name: बनाते समय निर्दिष्ट किया गया टोकन नाम (उदाहरण: उत्पाद बैकएंड सर्वर)।
• description: टोकन का विवरण (वैकल्पिक)।
• allowedReferrers: यह सूची तय करती है कि इस टोकन को किन origin से कॉल किया जा सकता है। सूची खाली हो, तो कोई पाबंदी नहीं लगती। ऊपर का उदाहरण सर्वर से कॉल किए जाने वाले टोकन का है, इसलिए वहाँ सूची खाली छोड़ दी गई है (लिखने के नियम और जाँच का तरीका जानने के लिए origin लिखने के नियम तथा Referer की जाँच देखें)।

role (बाइंड की जाने वाली SpaceRole) केवल निर्माण अनुरोध की बॉडी में भेजा जाने वाला इनपुट मान है, और प्रतिक्रिया संसाधन में शामिल नहीं होता। बाइंड की गई भूमिका इस टोकन के लिए बने एक समर्पित उपयोगकर्ता (प्रतिक्रिया का sys.user) को दी जाती है, इसलिए वह पुनर्प्राप्ति प्रतिक्रिया में role फ़ील्ड के रूप में वापस नहीं आती। ऊपर के उदाहरण में accessToken एक गुप्त मान है, इसलिए इसे उदाहरण स्ट्रिंग से बदल दिया गया है। वास्तव में यह SPCAT से शुरू होने वाला लंबा और अपारदर्शी स्ट्रिंग होता है, और जारी करने के बाद दोबारा पुनर्प्राप्त करने पर भी वही मान आता है।

सिस्टम गुण (sys)

हर Space Access Token अपने सामान्य सिस्टम गुण और टोकन-विशिष्ट गुण sys ऑब्जेक्ट में रखता है। space, user, createdBy, updatedBy Refer आकार ({ "sys": { "id", "type": "Refer", "targetType" } }) में आते हैं।

बॉडी गुण:

निर्माण अनुरोध की बॉडी के लिए विशेष इनपुट:

सुरक्षा: उजागर दायरे के अनुसार भूमिका बाइंडिंग

Space Access Token लिखने तक की अनुमति देने वाला ताकतवर टोकन है। इसे किस SpaceRole से बाइंड किया जाता है, यही इस टोकन के कर सकने वाले कामों की सीमा और साथ ही इसकी सुरक्षा सीमा बन जाती है। इस टोकन को सर्वर में रखना है या किसी उजागर क्लाइंट (जैसे अनाम पोस्टिंग) में, यह सेवा के अनुसार तय किया जाता है, और सुरक्षा "कहाँ छिपाया जाए" से नहीं, बल्कि बाइंड की गई भूमिका को उजागर दायरे के अनुसार सीमित करने से मिलती है।

• निर्माण अनुरोध के role में उस काम के लिए ज़रूरी क्रियाओं की ही अनुमति देने वाली सीमित SpaceRole की sys.id डालें। उत्पाद दर्ज करने वाला सर्वर टोकन हो तो उत्पाद Content Type पर केवल पढ़ने-लिखने की अनुमति देने वाली भूमिका, और उजागर अनाम पोस्टिंग टोकन हो तो पोस्ट Content Type पर केवल निर्माण (create) की अनुमति देने वाली भूमिका, इस तरह उजागर दायरे के अनुसार न्यूनतम बाइंडिंग करें।
• टोकन जितना उजागर क्लाइंट में दिखाया जाता है, भूमिका उतनी ही अधिक सीमित रखें। वह टोकन लीक हो जाने पर भी जितना संभाला जा सके उतने ही दायरे तक अनुमति देनी चाहिए। Administrator भूमिका या व्यापक लिखने वाली भूमिका को उजागर टोकन से बाइंड न करें। साथ ही SpaceRole सूची की पहली प्रविष्टि को बिना सोचे-समझे न लें, बल्कि अपनी इच्छित सीमित भूमिका की sys.id स्पष्ट रूप से निर्दिष्ट करें।
• टोकन ब्राउज़र से कॉल किया जाता हो, तो allowedReferrers से कॉल की जगह को भी सीमित करें। बाइंड की गई भूमिका तय करती है कि इस टोकन से क्या किया जा सकता है, और यह सूची तय करती है कि इसे कहाँ से कॉल किया जा सकता है (Referer की जाँच देखें)।
• आगंतुकों के सामने उजागर की जाने वाली केवल-पढ़ने वाली डिलीवरी के लिए, लिखने का अधिकार न रखने वाली Delivery Access Token अधिक उपयुक्त है। केवल जब लिखना ज़रूरी हो तभी Space Access Token का इस्तेमाल करें, और उसकी भूमिका को उजागर दायरे के अनुसार सीमित रखें।
• accessToken एक गुप्त मान है जो जारी करने के बाद भी उसी मान से पुनर्प्राप्त होता है। जहाँ उजागर करने की ज़रूरत न हो वहाँ इसे कोड, लॉग, भंडार या त्रुटि संदेशों में सादे रूप में न छोड़ें, और उजागर होने का संदेह हो तो इसे हटाकर निष्प्रभावी कर दें और नए टोकन से बदल लें।

स्थिति और बाधाएं

बनाते और संपादित करते समय पालन किए जाने वाले मान संबंधी प्रतिबंध।

बाइंडिंग और अनुमति से जुड़े नियम:

• बाइंड की जाने वाली role उस Space में वास्तव में मौजूद होनी चाहिए। न मौजूद भूमिका की sys.id डालने पर निर्माण अस्वीकार हो जाता है।
• कॉल करने वाला केवल वही भूमिका बाइंड कर सकता है जो उसके पास उस Space में है। यह प्रतिबंध इसलिए है ताकि कोई अपने पास न मौजूद भूमिका बाइंड करके टोकन को अपने से ऊँचा अधिकार न दे सके, और इस प्रतिबंध को तोड़ने वाला निर्माण अनुरोध अस्वीकार हो जाता है। हालाँकि उस Space का प्रशासक (Administrator भूमिका रखने वाला) इस प्रतिबंध से मुक्त है और किसी भी भूमिका को बाइंड कर सकता है।
• Space Access Token एक ऐसा संसाधन है जिसकी संख्या की सीमा होती है। वर्तमान योजना की जारी-संख्या सीमा पार होने पर निर्माण अस्वीकार हो जाता है। योजना-वार सीमाओं के लिए मूल्य योजनाएं देखें।
• जारी करने और प्रबंधन (बनाना, पुनर्प्राप्ति, संपादन, हटाना) के लिए कॉल करने वाले की भूमिका के settings में SETTING_SPACE_ACCESS_TOKEN होना ज़रूरी है। केवल-पढ़ने वाली Delivery Access Token जारी करने वाले SETTING_DELIVERY_ACCESS_TOKEN से यह अलग एक्शन है, इसलिए केवल डिलीवरी टोकन जारी करने की अनुमति देकर इस टोकन का जारी होना रोका जा सकता है (SpaceRole देखें)।
• यह API केवल कंसोल लॉगिन सत्र और Personal Access Token से कॉल किया जाता है। Space Access Token से खुद कोई दूसरा Space Access Token नहीं बनाया जा सकता, और बाइंड की गई भूमिका में SETTING_SPACE_ACCESS_TOKEN डाल देने पर भी यही बात लागू रहती है।

origin लिखने के नियम

allowedReferrers की प्रत्येक प्रविष्टि एक स्ट्रिंग है जो कॉल के लिए अनुमत किसी एक origin को दर्शाती है। इसे नीचे दिए स्वरूप में लिखा जाता है।

"allowedReferrers": [
  "https://shop.example.com",
  "https://*.shop.example.com",
  "http://localhost:3000"
]

सूची में अधिकतम 50 प्रविष्टियाँ रखी जा सकती हैं, और एक ही origin को दो बार नहीं डाला जा सकता। प्रत्येक प्रविष्टि को नीचे दिए नियमों का पालन करना होगा।

• स्कीम में केवल https लिखा जाता है। http केवल localhost, 127.0.0.1 और [::1] के लिए अनुमत है।
• वाइल्डकार्ड के रूप में केवल सबसे आगे का एक *. लेबल लिखा जाता है। पाथ में वाइल्डकार्ड नहीं लिखा जा सकता।
• होस्ट ASCII में लिखा जाता है। अंतरराष्ट्रीयकृत डोमेन को प्यूनिकोड रूप में डाला जाता है।
• पोर्ट 1 से 65535 तक होता है। इसे छोड़ देने पर स्कीम का डिफ़ॉल्ट पोर्ट (https के लिए 443, http के लिए 80) माना जाता है।
• प्रविष्टि में पाथ लिखा हो, तो अनुरोध का पाथ उससे पूरी तरह समान होने पर ही अनुरोध जाँच पार करता है। ब्राउज़र पाथ को परसेंट-एन्कोड करके भेजता है, इसलिए पाथ में केवल ASCII लिखा जाता है।
• उपयोगकर्ता जानकारी (user@), क्वेरी (?) या फ़्रैगमेंट (#) से युक्त प्रविष्टि अस्वीकार कर दी जाती है।

यह जाँच निर्माण, पूर्ण संपादन और आंशिक संपादन, इन तीनों पाथ पर लगती है। नियमों के विरुद्ध एक भी प्रविष्टि हो, तो सर्वर सूची को सहेजता नहीं और अनुरोध अस्वीकार कर देता है, तथा विरुद्ध पाई गई एक प्रविष्टि को त्रुटि के कारण में रखकर बता देता है (त्रुटियाँ देखें)।

Referer की जाँच

जारी करने के बाद इस टोकन से API कॉल करने पर, हर अनुरोध पर allowedReferrers लागू करके यह तय किया जाता है कि अनुरोध जाँच पार करेगा या नहीं।

• सूची खाली हो, तो कोई पाबंदी नहीं लगती। किसी भी origin से कॉल किया जाए, अनुरोध जाँच पार कर जाता है।
• सूची में एक भी प्रविष्टि हो, तो जाँच अनुरोध के Referer हेडर के मान से की जाती है। Origin हेडर को नहीं देखा जाता।
• Referer हेडर मौजूद न हो या उसका मान खाली हो, तो अनुरोध अस्वीकार कर दिया जाता है। सर्वर आपस में जो कॉल करते हैं उनकी तरह जहाँ Referer भेजा नहीं जाता, वहाँ काम आने वाले टोकन की सूची खाली छोड़ दी जाती है।
• जाँच पार करने के लिए Referer की स्कीम, होस्ट और पोर्ट, तीनों सूची की किसी एक प्रविष्टि से समान होने चाहिए। उस प्रविष्टि में पाथ भी हो, तो पाथ भी समान होना चाहिए।
• https://*.shop.example.com में admin.shop.example.com जैसे .shop.example.com पर ख़त्म होने वाले सभी होस्ट शामिल होते हैं, पर shop.example.com स्वयं शामिल नहीं होता। दोनों की अनुमति देनी हो, तो https://shop.example.com को एक और प्रविष्टि के रूप में डालें।
• यह जाँच इस टोकन से भेजे जाने वाले हर अनुरोध पर लगती है। CMA हो या CDA, किसी भी पाथ को कॉल करने पर यही नियम लागू रहता है।
• जाँच में रुके अनुरोध को HTTP 403 के साथ अस्वीकार कर दिया जाता है। लौटने वाला कोड नीचे त्रुटियाँ में दिया गया है।

त्रुटियाँ

ये कोड Space Access Token के साथ काम करते समय मिलते हैं। सभी संसाधनों में समान रूप से मिलने वाले कोड के लिए सामान्य त्रुटियाँ देखें।

API

नीचे दिए गए सभी एंडपॉइंट का आधार URL https://cma.weegloo.com/v1 है, और Authorization हेडर में CMA को प्रमाणित करने वाला Bearer टोकन आवश्यक है। Space Access Token के संपादन तथा आंशिक संपादन के लिए X-Weegloo-Version हेडर आवश्यक नहीं है।

संबंधित दस्तावेज़

• SpaceRole: इस टोकन से बाइंड की जाने वाली भूमिका (पढ़ने-लिखने का दायरा) को परिभाषित करता है।
• Delivery Access Token: आगंतुकों के सामने उजागर की जाने वाली केवल-पढ़ने वाली डिलीवरी टोकन (क्लाइंट के लिए)।
• Personal Access Token: पूरे खाते से बंधा सर्वर/CI के लिए Weegloo User टोकन।
• मूल्य योजनाएं: योजना-वार Space Access Token की जारी-संख्या सीमा।