Customer বা environment-প্রতি আলাদা key

Tokens-এর ওপর product বানালে জানতে চাইবেন কোন customer কত খরচ করছে, আর একজন customer বা একটা বিগড়ে যাওয়া service যেন সব উড়িয়ে না দেয়। এর জন্য Tokens আপনাকে দিয়েছে আলাদা API key। এই পেজে বলা আছে key দিয়ে কী হয় আর কী হয় না, যাতে আপনি ঠিক করতে পারেন কোথায় key ব্যবহার করবেন আর কোথায় কাজটা আপনার নিজের app-এ সারবেন।

আগে API keys পড়ে নিন, মূল কথাগুলো ওখানে। এই পেজ তার ওপর দাঁড়িয়ে।

Tokens এখানে কী পারে, কী পারে না#

Dashboard /api/keys-এর নিচের route-গুলোর সঙ্গে কথা বলে। এগুলোর authentication হয় আপনার sign in করা browser session দিয়ে (আর multi-factor check থাকলে সেটা দিয়ে), Tokens API key দিয়ে নয়, আর এগুলো সাপোর্ট করা কোনো public API-ও নয়। এগুলোর ওপর provisioning service বানাবেন না। Tokens CLI browser দিয়ে sign in করে, আর প্রতি login-এ একটা করে নতুন key পায়। এটা আপনার নিজের coding agent সাজানোর জন্য, customer-দের key বিলি করার জন্য নয়।

Key-তে কী কী সীমা দেওয়া যায়#

Dashboard-এ key বানানোর সময় এগুলো ঠিক করা যায়:

Key revoke হলে, বা তার অ্যাকাউন্ট suspend হলে, key কাজ করা বন্ধ করে দেয়। Rate limit, concurrency আর usage window key-র setting নয়, এগুলো আপনার অ্যাকাউন্টের, দেখুন rate limits।

Code থেকে কোনো key-র নিজের setting পড়তে চাইলে সেই key দিয়েই GET /v1/tokens/usage call করুন। Response-এর key object-এ তার monthlySpendCapUsd আর allowedModels পাবেন। একই response-এর plan, windows আর wallet অংশ পুরো অ্যাকাউন্টের কথা বলে, ওই key-র নয়।

curl -s https://tokens.bd/v1/tokens/usage \
  -H "Authorization: Bearer $CUSTOMER_KEY" | jq .key

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

প্রতিটা plan active key-র একটা সর্বোচ্চ সংখ্যা ঠিক করে দেয়, default 3 (pay-as-you-go অ্যাকাউন্টেও default 3)। আরেকটা বানাতে গেলে key_limit_reached আসে। Revoke করা key গোনা হয় না।

আপনার design এর ওপর নির্ভর করবে:

• হাতে গোনা কয়েকটা service বা environment (production, staging, একটা batch worker, একটা internal tool): প্রতিটার জন্য একটা করে key, default সীমার মধ্যেই হয়ে যায়।
• অনেক customer: customer-প্রতি একটা key তখনই চলে, যখন আপনার plan-এর সীমা যথেষ্ট বেশি। pricing-এ আপনার plan দেখুন, অথবা support-কে জিজ্ঞেস করুন আপনার জন্য কত সীমা সম্ভব। যে সংখ্যা নিশ্চিত করেননি, তার ওপর ভর করে design করবেন না।
• Key-র সীমার বেশি customer: পুরো product-এর জন্য একটা (বা কয়েকটা) key রাখুন, আর customer-প্রতি কাজটা সারুন আপনার নিজের app-এ, নিচে যেভাবে বলা আছে।

Environment আর service-এর জন্য key বানান#

সবচেয়ে কম যা রাখা ভালো:

Key বানানোর সময়ই cap আর model-এর তালিকা দিয়ে দিন, কারণ পরে বদলানো যায় না। কোনো cap ভুল হয়ে গেলে ঠিক মান দিয়ে নতুন key বানান, app-কে সেটাতে সরিয়ে নিন, তারপর পুরোনোটা revoke করুন। যেসব জায়গা আপনি ছেড়ে এসেছেন, সেখানে পুরোনো key-র secret রেখে আসবেন না।

Cap-এ পৌঁছালে কী হয়#

কোনো request key-কে মাসিক cap পার করিয়ে দিতে পারলে gateway সেটা model-এর কাছে যাওয়ার আগেই ফিরিয়ে দেয়:

{
  "error": {
    "message": "Monthly spend cap of $20.00 for this API key has been reached. Update the key cap or use an alternate key: https://tokens.bd/dashboard/billing",
    "type": "permission_denied_error",
    "code": "monthly_spend_cap_exceeded",
    "param": null,
    "request_id": "..."
  }
}

Status আসে 403, 429 নয়, আর Retry-After header-ও থাকে না: কয়েক সেকেন্ড অপেক্ষা করে লাভ নেই, key-টা পরের ক্যালেন্ডার মাস পর্যন্ত আটকে থাকে। Design করার সময় এই কথাগুলো মাথায় রাখুন:

• Check-টা যোগ করে দেখে এই মাসে key এখন পর্যন্ত কত খরচ করেছে, আর নতুন request-এর worst-case খরচ কত। সেটা নির্ভর করে max_tokens-এর ওপর (না দিলে 8,192 output token)। তাই বড় max_tokens-এর request cap-এ সত্যি পৌঁছানোর একটু আগেই ফিরে যেতে পারে, অথচ ছোট একটা তখনো পার পেয়ে যায়।
• খরচ গোনা হয় request শেষ হলে। Cap ছোঁয়ার মুহূর্তে যেসব request চলছে, সেগুলো তখনো গোনায় আসেনি, তাই key cap-এর সামান্য বেশিতে গিয়ে থামতে পারে।
• থামে শুধু ওই key। আপনার বাকি key, plan আর Wallet এতে প্রভাবিত হয় না, যদি না অ্যাকাউন্টেরই credit শেষ হয়ে যায় (দেখুন plans, credits and wallet)।
• Key rotate করলে তার খরচ শূন্য হয় না। Key-র পরিচয় একই থাকে, তাই এ মাসের usage cap-এর হিসাবে গোনা চলতে থাকে।

আপনার app-এ monthly_spend_cap_exceeded-কে ধরুন "এই customer বা environment তার বরাদ্দ শেষ করেছে" হিসেবে, outage হিসেবে নয়। নিজের message দেখান, আর retry করবেন না। সব code-এর তালিকা errors পেজে।

Customer-প্রতি খরচ মাপুন#

Tokens key-প্রতি খরচ দেখায় না। Usage পেজ, CSV export আর GET /v1/tokens/usage সবই পুরো অ্যাকাউন্টের হিসাব দেয়, আর CSV-তে key-র কোনো column নেই। তাই কোন customer কী ব্যবহার করল, সেই হিসাব রাখতে হবে আপনার app-কেই।

Customer-এর হয়ে করা প্রতিটা call-এর জন্য জমা রাখুন:

1. আপনার customer id,
2. x-tokens-request-id response header,
3. যে model call করেছেন, আর
4. response-এর usage object (Chat Completions-এ prompt_tokens, completion_tokens)।

তারপর token-এর সংখ্যাকে catalog-এর model-দামের সঙ্গে গুণ করলেই customer-প্রতি খরচ পাবেন। Plan-এর ছাড় বা allowance থাকলে আপনার যোগফল বিলের সঙ্গে পয়সায় পয়সায় মিলবে না, তাই কোনো request-এর আসল খরচ জানতে export করা CSV-র Request ID column ব্যবহার করুন (usage and alerts)।

Streaming response-এ request-এ "stream_options": {"include_usage": true} জুড়ে দিন, যাতে শেষ chunk-এ usage আসে। দেখুন streaming।

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://tokens.bd/v1",
    api_key=os.environ["TOKENS_API_KEY"],
)

def ask_for_customer(customer_id: str, prompt: str) -> str:
    raw = client.chat.completions.with_raw_response.create(
        model="deepseek/deepseek-v4.1-flash",
        messages=[{"role": "user", "content": prompt}],
        max_tokens=500,
    )
    completion = raw.parse()
    save_usage_row(  # your own database write
        customer_id=customer_id,
        request_id=raw.headers.get("x-tokens-request-id"),
        model=completion.model,
        prompt_tokens=completion.usage.prompt_tokens,
        completion_tokens=completion.usage.completion_tokens,
    )
    return completion.choices[0].message.content

Customer-প্রতি একটা key রাখলে key-র cap আপনাকে রক্ষা করে, কিন্তু তাদের বিল করার হিসাব এই উপরের তালিকা ধরেই করতে হবে।

Team account#

Tokens-এ role সহ team account (organization) আছে। এগুলো deployment ধরে চালু করা হয়, তাই আপনার dashboard-এ এখনো না-ও দেখতে পারেন। যেখানে চালু আছে, সেখানে key কোনো একজনের নয়, organization-এর। Code দেখে যা জানা গেছে: role হলো owner, admin, developer, billing আর viewer; billing আর viewer key বানাতে পারে না, developer শুধু নিজের বানানো key দেখে, আর owner ও admin organization-এর যেকোনো key rotate বা revoke করতে পারে। Organization প্রতিটা member-কে মাসিক spend cap-ও দিতে পারে, সেটায় পৌঁছালে 402 member_cap_reached আসে। আপনার অ্যাকাউন্টে কী আছে জানতে পড়ুন teams and roles।

Rotate আর revoke#

• Rotate করলে secret বদলে যায়, কিন্তু নাম, cap, allowed model আর usage history থাকে। পুরোনো secret সঙ্গে সঙ্গে অকেজো হয়ে যায়, কোনো grace period নেই। সেটা দিয়ে request গেলে 401 invalid_api_key আসে।
• Revoke করলে key চিরতরে বন্ধ। সেটা দিয়ে request গেলে 403 key_inactive আসে।

Downtime ছাড়া rotate করতে আগে একই setting দিয়ে দ্বিতীয় একটা key বানান, সেটা app-এ deploy করুন, তারপর পুরোনোটা revoke করুন। Key-র setting বদলানো যায় না বলে "একই setting" মানে আবার হাতে লিখে দেওয়া। Key leak হলে সঙ্গে সঙ্গে rotate বা revoke করুন, তারপর usage-এ দেখুন চেনা নেই এমন কোনো request আছে কি না।

আপনার নিজের app-কে কী করতে হবে#

• User-কে key-র সঙ্গে মেলান। Customer বা environment থেকে key-তে যাওয়ার একটা table রাখুন। Secret দেখানো হয় একবারই, তাই সেটা রাখুন secrets manager-এ বা encrypted column-এ, কখনো plain text-এ নয়, আর log-এ তো নয়ই।
• Key server-এই রাখুন। Tokens browser থেকে call নেয় না (CORS header নেই), আর browser বা mobile app-এর ভেতরের সবকিছু user-রা বের করে নিতে পারে। আপনার client call করবে আপনার backend-কে, আর backend call করবে Tokens-কে। দেখুন browser and mobile apps।
• অপব্যবহার নিজেই ঠেকান। Customer-প্রতি rate limit, request-এর size-এর সীমা আর max_tokens-এর একটা সর্বোচ্চ মান আপনার code-এই থাকা উচিত, কারণ Tokens-এর rate limit অ্যাকাউন্ট ধরে।
• Key-র error সামলান। monthly_spend_cap_exceeded, model_not_allowed_on_key, key_inactive আর invalid_api_key-কে আপনার product-এ একটা পরিষ্কার অবস্থায় রূপ দিন, আর key_inactive ও invalid_api_key-তে নিজেকে alert পাঠান, কারণ এ দুটোর মানে আপনার নিজের configuration ভুল।
• অ্যাকাউন্টের দিকে নজর রাখুন। প্রতিটা key খরচ করে একই plan আর Wallet থেকে। Dashboard-এ low-balance আর usage alert চালু করুন (usage and alerts), আর launch-এর আগে production checklist দেখে নিন।
• শর্তগুলো পড়ুন। আপনার অ্যাকাউন্টের ওপর কী বানাতে আর বিক্রি করতে পারবেন, তা ঠিক করে terms of service, এই পেজ নয়।

Checklist#

1. Key-র সংখ্যা গুনুন, আর design করার আগে আপনার plan-এর active-key সীমার সঙ্গে মিলিয়ে নিন।
2. প্রতিটা key বানান cap আর allowed-models তালিকা দিয়ে, কারণ পরে যোগ করা যায় না।
3. প্রতিটা secret server-এ রাখুন, আর প্রতিটা request-এর সঙ্গে আপনার customer id রেকর্ড করুন।
4. Cap-এর পথটা পরীক্ষা করুন: খুব ছোট cap দিয়ে একটা key বানিয়ে দেখুন আপনার app 403 monthly_spend_cap_exceeded ঠিকমতো সামলায় কি না।
5. Key কীভাবে rotate করবেন লিখে রাখুন, আর দরকার পড়ার আগে একবার করে দেখুন।