# API keys

> Tokens API key তৈরি, সীমা বেঁধে দেওয়া, নিরাপদে রাখা, rotate ও revoke করা, আর key-সংক্রান্ত error বোঝা: invalid_api_key, key_inactive, model_not_allowed_on_key এবং monthly_spend_cap_exceeded।

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

## API key তৈরি করুন

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

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

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

| Field                   | আবশ্যক কি না | কী কাজ করে                                                                                                   |
| ----------------------- | ------------ | ------------------------------------------------------------------------------------------------------------ |
| Name                    | হ্যাঁ         | আপনার নিজের জন্য একটা লেবেল। key কোথায় থাকবে সেটাই লিখুন: "laptop", "github-actions", "support-bot"।        |
| Monthly spend cap (USD) | না           | এক ক্যালেন্ডার মাসে এই key সর্বোচ্চ কত খরচ করতে পারবে।                                                       |
| Allowed models          | না           | শুধু যেসব model id এই key দিয়ে call করা যাবে। ফাঁকা রাখলে আপনার অ্যাকাউন্ট যত model চালাতে পারে সবই চলবে।      |

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

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

```bash
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-গুলোই আসে।

:::warning[তৈরির সময়ই সীমা ঠিক হয়ে যায়]
Key বানানোর পর spend cap আর allowed-models তালিকা বদলানো যায় না। কোনোটা বদলাতে চাইলে নতুন সীমা দিয়ে নতুন key বানান, tool-গুলো সেটাতে সরিয়ে নিন, তারপর পুরোনোটা revoke করুন।
:::

## কয়টা 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](/pricing) দেখে বেশি সীমার plan-এ যান।

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

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

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

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

```bash title=".env"
TOKENS_API_KEY=tok_live_your_key
```

```bash title=".gitignore"
.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 করবেন না।

:::danger[Key leak হলে]
সঙ্গে সঙ্গে [/dashboard/keys](/dashboard/keys)-এ গিয়ে rotate বা revoke করুন, তারপর [usage](/dashboard/usage)-এ দেখুন চেনা নেই এমন কোনো request আছে কি না। Commit মুছে দিলে লাভ হয় না: remote-এ যা push হয়েছে, ধরে নিন সেটা কেউ copy করে নিয়েছে।
:::

## 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](/docs/tokens-cli)-তে `logout` করলে শুধু আপনার কম্পিউটারের copy-টা মুছে যায়। Key-টা এখানে revoke না করা পর্যন্ত চালু থাকে।

## Key-র error code

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

```json
{
  "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": "..."
  }
}
```

| HTTP | Code                         | মানে                                                                                       | কী করবেন                                                              |
| ---- | ---------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| 401  | `missing_api_key`            | `Authorization` বা `x-api-key` header নেই                                                  | আপনার tool যে shell-এ চলে, সেখানে variable set আছে কি না দেখুন        |
| 401  | `invalid_api_key`            | Key-টা নেই, ভুল টাইপ হয়েছে, অথবা rotate হয়ে গেছে                                          | এখনকার secret-টা copy করুন, অথবা নতুন key বানান                        |
| 403  | `key_inactive`               | Key-টা আর active নেই (যেমন suspend হয়েছে)                                                 | অন্য key ব্যবহার করুন, অথবা suspend হওয়ার কারণ Support-কে জিজ্ঞেস করুন |
| 403  | `key_expired`                | Key-টা administrator মেয়াদ দিয়ে provision করেছিলেন, আর সেই মেয়াদ শেষ                      | নতুন key বানান                                                        |
| 403  | `model_not_allowed_on_key`   | Model-টা এই key-র allowed তালিকায় নেই; message-এ allowed model-গুলো লেখা থাকে              | Allowed কোনো model নিন, অথবা এটাসহ নতুন key বানান                      |
| 403  | `monthly_spend_cap_exceeded` | এই key মাসিক cap-এ পৌঁছে গেছে                                                              | পরের ক্যালেন্ডার মাস পর্যন্ত অপেক্ষা করুন, অথবা বেশি cap-এর key বানান   |
| 403  | `account_suspended`          | পুরো অ্যাকাউন্টটাই suspend করা                                                              | [support](/docs/support)-এর সঙ্গে যোগাযোগ করুন                         |

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

---
Page: https://tokens.bd/bn/docs/api-keys