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

> Tokens-এর ওপর product বানালে: key-তে কী কী সীমা দেওয়া যায়, key কীভাবে তৈরি ও revoke হয় (শুধু dashboard থেকে, key-management API নেই), কয়টা key রাখা যায়, customer-প্রতি খরচ কীভাবে মাপবেন, আর আপনার নিজের app-কে কী করতে হবে।

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

আগে [API keys](/docs/api-keys) পড়ে নিন, মূল কথাগুলো ওখানে। এই পেজ তার ওপর দাঁড়িয়ে।

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

| আপনি হয়তো ভাবছেন                       | আসলে যা আছে                                                                                                                                       |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Spend cap দিয়ে key বানানো              | হ্যাঁ, dashboard-এ [/dashboard/keys](/dashboard/keys)-এ                                                                                           |
| Key-কে কয়েকটা model-এ সীমাবদ্ধ করা     | হ্যাঁ, তৈরির সময় একটা allowed-models তালিকা দেওয়া যায়                                                                                          |
| API দিয়ে key তৈরি, rotate বা revoke    | **না।** `tok_live_` key দিয়ে call করার মতো কোনো key-management endpoint নেই                                                                      |
| Key-র মেয়াদ শেষের তারিখ ঠিক করা        | **না।** তৈরির ফর্মে expiry-র field নেই। `key_expired` আসে শুধু সেই key-তে, যেটা কোনো administrator মেয়াদ দিয়ে provision করেছেন                    |
| পরে key-র cap বা model বদলানো           | **না।** দুটোই তৈরির সময় ঠিক হয়ে যায়                                                                                                            |
| প্রতিটা key-র আলাদা rate limit          | **না।** মিনিটপ্রতি request আর concurrency অ্যাকাউন্টের, সব key মিলে ভাগ করে নেয়                                                                  |
| Dashboard বা API-তে key-প্রতি খরচ        | **না।** দেখুন [customer-প্রতি খরচ মাপুন](#track-spend-per-customer)                                                                               |
| এক অ্যাকাউন্টে শত শত key                | শুধু আপনার plan অনুমতি দিলে। Default 3টা active key                                                                                              |

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

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

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

| Setting                 | কী প্রভাব                                                                                                                                     |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Name                    | সর্বোচ্চ 64 অক্ষর। key কার, সেটা এখানে লিখে রাখুন: `acme-prod`, `staging`, `batch-worker`।                                                    |
| Monthly spend cap (USD) | এক ক্যালেন্ডার মাসে key সর্বোচ্চ কত খরচ করতে পারবে। ফাঁকা রাখলে, আপনার plan-এ default cap থাকলে key সেটাই পায়।                                  |
| Allowed models          | শুধু যেসব model id এই key দিয়ে call করা যাবে। ফাঁকা মানে আপনার অ্যাকাউন্ট যত model চালাতে পারে সবই। `GET /v1/models` শুধু allowed model দেখায়। |

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

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

```bash
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](/pricing)-এ আপনার plan দেখুন, অথবা [support](/docs/support)-কে জিজ্ঞেস করুন আপনার জন্য কত সীমা সম্ভব। যে সংখ্যা নিশ্চিত করেননি, তার ওপর ভর করে design করবেন না।
- **Key-র সীমার বেশি customer**: পুরো product-এর জন্য একটা (বা কয়েকটা) key রাখুন, আর customer-প্রতি কাজটা সারুন আপনার নিজের app-এ, নিচে যেভাবে বলা আছে।

:::note
বেশি key মানে বেশি throughput নয়। মিনিটপ্রতি সীমা আর concurrency সীমা গোনা হয় অ্যাকাউন্ট ধরে, তাই দশটা key-ও একটা key-র মতোই একই সীমা ভাগ করে নেয়। কোনো customer একসঙ্গে অনেক request পাঠাতে পারলে Tokens-এর সামনে নিজের একটা সীমা বসান, যেমন customer-প্রতি একটা queue বা semaphore।
:::

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

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

| Key             | Cap                                                  | Allowed models                  |
| --------------- | ---------------------------------------------------- | ------------------------------- |
| `prod`          | এক মাসে একটা bug-এর কারণে যতটা হারানো মেনে নিতে পারেন | আপনার product যে model-গুলো চালায় |
| `staging`       | সামান্য কিছু                                         | একটা সস্তা model                |
| `ci` বা `batch` | Job-টার খরচ, সঙ্গে কিছুটা বাড়তি                      | Job-টার যে model-টা লাগে, শুধু সেটা |

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

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

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

```json
{
  "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](/docs/plans-and-wallet))।
- Key rotate করলে তার খরচ শূন্য হয় না। Key-র পরিচয় একই থাকে, তাই এ মাসের usage cap-এর হিসাবে গোনা চলতে থাকে।

আপনার app-এ `monthly_spend_cap_exceeded`-কে ধরুন "এই customer বা environment তার বরাদ্দ শেষ করেছে" হিসেবে, outage হিসেবে নয়। নিজের message দেখান, আর retry করবেন না। সব code-এর তালিকা [errors](/docs/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](/models)-এর model-দামের সঙ্গে গুণ করলেই customer-প্রতি খরচ পাবেন। Plan-এর ছাড় বা allowance থাকলে আপনার যোগফল বিলের সঙ্গে পয়সায় পয়সায় মিলবে না, তাই কোনো request-এর আসল খরচ জানতে export করা CSV-র **Request ID** column ব্যবহার করুন ([usage and alerts](/docs/usage-and-alerts))।

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

```python title="record_usage.py"
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](/docs/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](/dashboard/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](/docs/browser-and-mobile)।
- **অপব্যবহার নিজেই ঠেকান।** 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](/docs/usage-and-alerts)), আর launch-এর আগে [production checklist](/docs/production-checklist) দেখে নিন।
- **শর্তগুলো পড়ুন।** আপনার অ্যাকাউন্টের ওপর কী বানাতে আর বিক্রি করতে পারবেন, তা ঠিক করে [terms of service](/terms), এই পেজ নয়।

## 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 করবেন লিখে রাখুন, আর দরকার পড়ার আগে একবার করে দেখুন।

---
Page: https://tokens.bd/bn/docs/one-key-per-customer