API keys

/v1-এ প্রতিটা call-এ পরিচয় দেখাতে লাগে Tokens API key। এই পাতায় আছে key তৈরি, key-তে বসানো যায় এমন দুটো সীমা, নিরাপদে রাখা, rotate আর revoke করা, আর key-সংক্রান্ত প্রতিটা error-এর মানে।

API key তৈরি করুন#

/dashboard/keys-এ গিয়ে key তৈরি করুন। তার আগে দুটো শর্ত মিলতে হবে:

• আপনার ইমেইল ঠিকানা verify করা, এবং
• একটা active plan আছে, অথবা Wallet-এ ব্যালান্স শূন্যের বেশি।

ফর্মে যা চায়:

Secret-টা দেখতে tok_live_ আর তার পরে 48টা hex অক্ষর। তৈরির ঠিক পরে এটা দেখানো হয় একবারই। Tokens শুধু hash জমা রাখে, তাই আর কেউ এটা আপনাকে দেখাতে পারবে না। হারিয়ে ফেললে key rotate করুন, নয়তো নতুন key বানান।

দুটো header-এর যেকোনোটায় key পাঠানো যায়:

curl https://tokens.bd/v1/models -H "Authorization: Bearer $TOKENS_API_KEY"
curl https://tokens.bd/v1/models -H "x-api-key: $TOKENS_API_KEY"

মাসিক spend cap আর allowed model ঠিক করুন#

শুধু একটা সেটিং বদলাতে চাইলে spend cap-টাই দিন। Coding agent লম্বা loop চালায়, আর cap থাকলে বেহিসাবি session বিল হয়ে আসার বদলে একটা error হয়ে থামে।

• Monthly spend cap। ক্যালেন্ডার মাসের শুরু থেকে key-টা কত খরচ করেছে, Tokens তা যোগ করে রাখে। প্রতিটা request-এর আগে ওই request-এ সর্বোচ্চ কত খরচ হতে পারে সেটাও ধরা হয়। তাই যে request key-কে cap পার করিয়ে দিতে পারে, ঠিক cap-এ পৌঁছানোর একটু আগেই সেটা monthly_spend_cap_exceeded দিয়ে ফিরিয়ে দেওয়া হয়। Field ফাঁকা রাখলে আর আপনার plan-এ default cap থাকলে, key-টা সেই default cap পায়।
• Allowed models। Tool-টার যে model সত্যিই লাগে, key-কে শুধু সেটাতেই সীমাবদ্ধ করুন। যে CI job একটা সস্তা model চালায়, সে যেন দামি model call করতে না পারে। সীমিত key দিয়ে GET /v1/models call করলে শুধু allowed model-গুলোই আসে।

কয়টা key রাখা যায়#

প্রতিটা plan active key-র একটা সর্বোচ্চ সংখ্যা ঠিক করে দেয়। Default 3, আর plan ছাড়া pay-as-you-go অ্যাকাউন্টেও default 3। সীমায় পৌঁছে গেলে আরেকটা বানাতে চাইলে key_limit_reached আসে ("Your ... plan allows N active keys")। যে key আর লাগে না সেটা revoke করুন, অথবা pricing দেখে বেশি সীমার plan-এ যান।

প্রতিটা tool বা machine-এর জন্য আলাদা key রাখা ভালো অভ্যাস। এতে usage dashboard পড়তে সুবিধা হয়, আর একটা key leak হলে বাকি সব না থামিয়ে শুধু সেটাই revoke করা যায়।

API key নিরাপদে রাখুন#

Key-কে পাসওয়ার্ডের মতো দেখুন। এটা আপনার টাকা খরচ করে।

• Environment variable ব্যবহার করুন। এই docs-এর সব উদাহরণ TOKENS_API_KEY পড়ে।
• Project-এর জন্য .env file রাখুন, আর git-এ সেটা ignore করুন:

TOKENS_API_KEY=tok_live_your_key

.env
.env.*

• CI-তে key-টা আপনার CI provider-এর secret হিসেবে রাখুন, আর run-এর সময় environment variable হিসেবে দিন।
• Client-side code-এ কখনো key রাখবেন না। Browser আর mobile app-এর source user-দের হাতে চলে যায়। তা ছাড়া Tokens-এ browser থেকে call-ই চলে না (response-এ CORS header নেই)। মাঝখানে একটা ছোট server বা serverless function রাখুন, key থাকবে সেখানে।
• Agent config file। Claude Code, OpenCode আর Crush key রাখে আপনার home directory-র config file-এ। নিজের machine-এ সেটা ঠিক আছে, কিন্তু ওই file-গুলো dotfiles repository-তে commit করবেন না।

API key rotate করুন#

Rotate করলে secret বদলে যায়, কিন্তু key-র বাকি সবকিছু থাকে: নাম, spend cap, allowed model আর usage history।

পুরোনো secret সঙ্গে সঙ্গে অকেজো হয়ে যায়। কোনো grace period নেই। যে tool এখনো সেটা ব্যবহার করছে, তার পরের request-এই 401 invalid_api_key আসবে। তাই এই ক্রমে করুন:

1. যেসব জায়গায় key ব্যবহার হয় (env var, CI secret, agent config) সেগুলো বদলানোর জন্য তৈরি রাখুন।
2. Key-র পাশে Rotate চাপুন আর নতুন secret copy করুন।
3. পুরোনোটা যেখানে যেখানে ছিল, সব জায়গায় নতুনটা বসান।

অল্প সময়ের জন্যও বন্ধ থাকা চলবে না? আগে দ্বিতীয় একটা key বানান, tool-গুলো সেটাতে সরিয়ে নিন, তারপর পুরোনোটা revoke করুন।

API key revoke করুন#

Revoke করলে key চিরতরে বন্ধ হয়ে যায়, আর তা কার্যকর হয় সঙ্গে সঙ্গে। যে key আর লাগে না, কিংবা যেটা leak হয়েছে বলে সন্দেহ, সেটা revoke করুন। Revoke করা key আপনার active-key সীমায় গোনা হয় না।

Tokens CLI-তে logout করলে শুধু আপনার কম্পিউটারের copy-টা মুছে যায়। Key-টা এখানে revoke না করা পর্যন্ত চালু থাকে।

Key-র error code#

OpenAI-style endpoint-এ error আসে OpenAI-র ধাঁচে, আর /v1/messages-এ Anthropic-এর ধাঁচে (দেখুন Errors)। সঙ্গে একটা request_id থাকে, যা আপনি support-কে জানাতে পারেন:

{
  "error": {
    "message": "Model 'example/model' is not permitted on this API key. Permitted models: deepseek/deepseek-v4.1-flash.",
    "type": "permission_denied_error",
    "code": "model_not_allowed_on_key",
    "param": null,
    "request_id": "..."
  }
}

monthly_spend_cap_exceeded আসে key-র সীমার কারণে। বদলে যদি আপনার plan বা Wallet-ই শেষ হয়ে যায়, তাহলে দেখবেন window_exhausted, insufficient_credits বা tier_permission_denied। এগুলো আছে plans, credits and wallet আর errors-এ।