अपनी Key सत्यापित करें

GET /ping Developer REST API के विरुद्ध कैननिकल पहला कॉल है: यह पुष्टि करता है कि आपकी key काम कर रही है और ठीक-ठीक बताता है कि वह क्या कर सकती है। key बनाने के तुरंत बाद यह कॉल करें ताकि रिसोर्स endpoints पर कुछ बनाने से पहले क्रेडेंशियल सत्यापित हो जाए।

GET /ping

कॉल करने वाले क्रेडेंशियल को सत्यापित करता है और बताता है कि यह किस डेवलपर API कॉन्टेक्स्ट में रिज़ॉल्व होता है। सत्यापित कॉन्टेक्स्ट के साथ 200 लौटाता है, या यदि key अनुपस्थित, गलत-स्वरूप, निरस्त या अज्ञात है तो 401 लौटाता है।

Scope: कोई नहीं — कोई भी वैध key (या साइन-इन सेशन) · सफलता: 200

हर रिसोर्स endpoint के विपरीत, /ping scope द्वारा सीमित नहीं है। कोई भी एकल scope रखने वाली key — यहाँ तक कि केवल knowledge:read — स्वयं को सत्यापित करने के लिए इसे कॉल कर सकती है। यही इसका उद्देश्य है: key को जो करने की अनुमति है उससे निरपेक्ष रूप से आपको यह पुष्टि कर पाना चाहिए कि key काम कर रही है।

curl https://cuneiform.chat/api/developer/v1/ping \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx"

key से प्रमाणित अनुरोध वह ऑर्गनाइज़ेशन लौटाता है जिसके लिए key कार्य करती है, प्रमाणित रोल, आपने कैसे प्रमाणीकरण किया, और साथ ही कॉल करने वाली key का id, उसका नाम, उसके अंतिम चार अक्षर और उसके प्रदत्त scopes:

{
  "object": "developer_api_context",
  "organization": {
    "id": "org_8s2k1d",
    "name": "Acme Inc"
  },
  "role": "owner",
  "authenticated_via": "api_key",
  "api_key": {
    "id": "key_4f9a2c",
    "name": "Production CI",
    "last4": "ab12",
    "scopes": ["agents:read", "agents:query", "knowledge:read"]
  }
}

scopes ऐरे ठीक वही सेट है जो key को प्रदान किया गया था — इस पर निर्भर होने से पहले यह पुष्टि करने के लिए इसका उपयोग करें कि key के पास वह एक्सेस है जिसकी आपके इंटीग्रेशन को आवश्यकता है।

त्रुटियाँ: 401, 429, 500।

प्रतिक्रिया आपको क्या बताती है

यह कभी क्या नहीं लौटाता

प्रतिक्रिया deny-by-default है: यह केवल सत्यापित अनुरोध कॉन्टेक्स्ट से बनती है, इसलिए यह कभी किसी अन्य ऑर्गनाइज़ेशन का डेटा नहीं लौटा सकती और न ही कोई आंतरिक key फ़ील्ड उजागर करती है। पूर्ण key सीक्रेट, लुकअप hash, निर्माता, कच्चा आंतरिक id और रोल की अंतर्निहित RBAC परमिशन कभी उपस्थित नहीं होतीं — केवल ऊपर दिए गए चार key फ़ील्ड।

यह कब विफल होता है

अनुपस्थित, गलत-स्वरूप, निरस्त या अज्ञात key मानक एरर एनवेलप के साथ 401 लौटाती है:

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key is missing or invalid."
  }
}

चूँकि /ping scope द्वारा सीमित नहीं है, यह कभी scope कारण से 403 नहीं लौटाता — 401 का अर्थ है कि क्रेडेंशियल स्वयं वैध नहीं है।