API Keys
একটি ডেভেলপার API key হলো সেই ক্রেডেনশিয়াল যা আপনার কোড প্রতিটি অনুরোধে উপস্থাপন করে। keys অ্যাডমিন প্যানেলে তৈরি ও পরিচালিত হয় — API-এর মাধ্যমে নয় — এবং প্রতিটি key একটি এনভায়রনমেন্ট, scopes-এর একটি সেট এবং একটি সিক্রেট বহন করে যা কেবল একবার প্রকাশ করা হয়।
keys কোথায় পরিচালিত হয়
key পরিচালনা প্যানেলের ইন-প্যানেল ডেভেলপার কনসোলে /org/developer-api-তে থাকে। keys তৈরি, তালিকাভুক্ত, রোটেট ও প্রত্যাহার করা হলো অ্যাডমিন অ্যাকশন, যা আপনার স্বাভাবিক সাইন-ইন সেশন দিয়ে সেখানে সম্পন্ন হয় — সেগুলো ইচ্ছাকৃতভাবে cuk_-প্রমাণীকৃত /v1 সারফেসের অংশ নয় (একটি ফাঁস হওয়া key কখনো অন্য একটি key তৈরি বা প্রত্যাহার করতে পারে না)। কনসোলটি Starter ও তার উপরে উপলব্ধ; trial organizations keys তৈরি করতে পারে না।
key ফরম্যাট
একটি key সিক্রেটের রূপ cuk_<env>_<random> — উদাহরণস্বরূপ:
cuk_live_M8s2k...<random>এর তিনটি অংশ আছে:
| অংশ | অর্থ |
|---|---|
cuk | ব্র্যান্ড প্রিফিক্স — প্রতিটি Cuneiform Chat key cuk_ দিয়ে শুরু হয়। |
<env> | এনভায়রনমেন্ট: live বা test। |
<random> | একটি দীর্ঘ, URL-নিরাপদ র্যান্ডম সিক্রেট। |
এনভায়রনমেন্ট
প্রতিটি key একটি এনভায়রনমেন্টের জন্য তৈরি হয়:
| এনভায়রনমেন্ট | প্রিফিক্স | ব্যবহার |
|---|---|---|
live | cuk_live_ | আপনার আসল ডেটার বিপরীতে প্রোডাকশন ট্রাফিক। |
test | cuk_test_ | ডেভেলপমেন্ট ও ইন্টিগ্রেশন টেস্টিং। |
এক-বারের প্রকাশ
সম্পূর্ণ সিক্রেট ঠিক একবার দেখানো হয় — আপনি যে মুহূর্তে একটি key তৈরি বা রোটেট করেন। এর পরে, কেবল key-এর প্রিফিক্স (cuk_<env>_) এবং এর শেষ চারটি অক্ষর প্রদর্শিত হয়, যাতে আপনি একটি তালিকায় একটি key চিনতে পারেন এটি পুনরুদ্ধারযোগ্য না হওয়া ছাড়াই।
আপনি একটি সিক্রেট হারালে, এটি পুনরুদ্ধার করতে পারবেন না — একটি নতুন পেতে key রোটেট করুন (যা পুরোনো সিক্রেটটি প্রত্যাহার করে), অথবা এটি প্রত্যাহার করে একটি নতুন তৈরি করুন।
Scopes
একটি key পাঁচটি scopes-এর একটি উপসেট পায়। প্রতিটি scope অপারেশনের একটি গ্রুপ আনলক করে এবং key তৈরিকারী রোলের RBAC অনুমতি দ্বারা অতিরিক্তভাবে সীমাবদ্ধ — একটি key তার নির্মাতা প্যানেলে যা ধারণ করে তার চেয়ে বেশি কখনো প্রদান করতে পারে না।
| Scope | যা আনলক করে | RBAC সিলিং |
|---|---|---|
knowledge:read | ডকুমেন্ট, ফোল্ডার ও tags তালিকাভুক্ত, সার্চ ও আনয়ন করা। | কনটেন্ট read অনুমতি প্রয়োজন। |
knowledge:write | ডকুমেন্ট আপলোড, মুছে ফেলা ও সংগঠিত করা; ফোল্ডার ও tags তৈরি/আপডেট/মুছে ফেলা। | কনটেন্ট upload + update অনুমতি প্রয়োজন। |
agents:read | agents ও তাদের কনফিগারেশন তালিকাভুক্ত ও আনয়ন করা। | agent read অনুমতি প্রয়োজন। |
agents:write | agents তৈরি ও আপডেট করা; কনফিগারেশন আপডেট করা; মুছে ফেলা ও পুনরুদ্ধার করা। | agent create + update অনুমতি প্রয়োজন (মুছে ফেলা/পুনরুদ্ধারের জন্য agent-delete অনুমতিও প্রয়োজন)। |
agents:query | একটি agent চালানো (POST /agents/{id}/query)। | agent read অনুমতি প্রয়োজন। |
একটি key-কে কেবল তার প্রয়োজনীয় scopes দিন। একটি অনুরোধ যা তার scopes-এর বাইরের একটি endpoint কল করে তা 403 permission_error (invalid_scope) দিয়ে প্রত্যাখ্যাত হয়।
keys পরিচালনা (কনসোলে)
/org/developer-api-তে ডেভেলপার কনসোল সমর্থন করে:
- তৈরি — একটি এনভায়রনমেন্ট ও scopes বেছে নিন; সিক্রেটটি একবার প্রকাশ করা হয়।
- তালিকা — প্রতিটি key-এর প্রিফিক্স, শেষ চারটি অক্ষর, scopes ও স্ট্যাটাস দেখুন (সিক্রেট আর কখনো দেখানো হয় না)।
- রোটেট — একটি key-এর জন্য একটি নতুন সিক্রেট তৈরি করুন এবং পূর্ববর্তীটি প্রত্যাহার করুন। এটি একটি নিয়মিত সময়সূচীতে অথবা একটি key ফাঁস হয়ে থাকতে পারলে অবিলম্বে ব্যবহার করুন।
- প্রত্যাহার — একটি key স্থায়ীভাবে নিষ্ক্রিয় করুন। একটি প্রত্যাহৃত key উপস্থাপনকারী অনুরোধ
401দিয়ে প্রত্যাখ্যাত হয়।
এই অ্যাকশনগুলোর কোনোটির জন্য কোনো API endpoint নেই — ডিজাইন অনুযায়ী সেগুলো কেবল প্যানেলে।