আপনার Key যাচাই করুন

GET /ping হলো Developer REST API-এর বিপরীতে ক্যাননিকাল প্রথম কল: এটি নিশ্চিত করে যে আপনার key কাজ করছে এবং ঠিক কী করতে পারে তা জানায়। একটি key তৈরি করার পরেই এই কলটি করুন, যাতে রিসোর্স endpoint-গুলোর উপর কিছু গড়ে তোলার আগে ক্রেডেনশিয়ালটি যাচাই করা যায়।

`GET /ping`

কলকারী ক্রেডেনশিয়াল যাচাই করে এবং এটি যে ডেভেলপার API কনটেক্সটে রিজলভ হয় তা জানায়। যাচাইকৃত কনটেক্সট সহ 200 ফেরত দেয়, অথবা key অনুপস্থিত, ত্রুটিপূর্ণ, প্রত্যাহারকৃত বা অজানা হলে 401 ফেরত দেয়।

Scope: কোনোটি নয় — যেকোনো বৈধ key (অথবা সাইন-ইন করা সেশন) · সফলতা: 200

প্রতিটি রিসোর্স endpoint-এর বিপরীতে, /ping scope দ্বারা সীমাবদ্ধ নয়। যে key কোনো একটি scope বহন করে — এমনকি শুধু knowledge:read — সেটিও নিজেকে যাচাই করতে এটি কল করতে পারে। এটাই উদ্দেশ্য: 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।

প্রতিক্রিয়া আপনাকে যা জানায়

ফিল্ড	অর্থ
`object`	সর্বদা `developer_api_context`।
`organization`	ক্রেডেনশিয়াল যে অর্গানাইজেশনের হয়ে কাজ করে — `id` এবং প্রদর্শন `name`। প্রতিটি অনুরোধ এই অর্গানাইজেশনে সীমাবদ্ধ; আপনি কখনো একটি অর্গানাইজেশন id পাঠান না।
`role`	ক্রেডেনশিয়াল যে রোলে কাজ করে (উদাহরণস্বরূপ `owner`, `admin` বা `member`)। একটি key কখনো এই রোল প্যানেলে যা করতে পারত তার চেয়ে বেশি করতে পারে না।
`authenticated_via`	`cuk_…` key-এর জন্য `api_key`, অথবা অ্যাডমিন প্যানেলে সাইন-ইন করা সেশনের জন্য `session`।
`api_key`	কলকারী key-এর স্ব-বর্ণনা — `id`, `name`, `last4` এবং প্রদত্ত `scopes`। `authenticated_via` যখন `session` হয় তখন এটি `null` (কোনো key নেই)।

এটি যা কখনো ফেরত দেয় না

প্রতিক্রিয়াটি 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 মানে ক্রেডেনশিয়ালটি নিজেই বৈধ নয়।