# Authentication

> Base URL, দুই ধরনের auth header, tok_live_ key-এর format, আর 401 ও 403 error code-এর মানে।

Tokens API-তে প্রতিটা request-এর সঙ্গে একটা platform key header-এ পাঠাতে হয়। এই পেজে আছে base URL, কোন কোন header চলে, key-এর format কেমন, আর authentication error-এর প্রতিটার মানে কী।

## Base URL

একই host-এ Tokens দুটো surface দেয়। কোনটা নেবেন সেটা ঠিক হয় client দেখে, model দেখে না।

| Client-এর ধরন        | Base URL               | সাধারণত যেসব tool                                                    |
| -------------------- | ---------------------- | ------------------------------------------------------------------- |
| OpenAI-compatible    | `https://tokens.bd/v1` | OpenAI SDKs, Cursor, Cline, Aider, OpenCode, Codex CLI              |
| Anthropic-compatible | `https://tokens.bd`    | Anthropic SDKs, Claude Code (এরা নিজেই শেষে `/v1/messages` জুড়ে নেয়) |

কোনো tool "API base" বা "base URL" চাইলে আর সেটা OpenAI-ধাঁচের হলে `/v1` সহ দিন। Anthropic-ধাঁচের হলে `/v1` বাদ দিন, কারণ SDK নিজেই ওটা জুড়ে দেয়। প্রথম request-এই 404 আসার সবচেয়ে বড় কারণ এখানে ভুল করা।

কোনো tool নিজে থেকে endpoint খুঁজে নিতে চাইলে একটা public config endpoint আছে। এতে authentication লাগে না:

```bash
curl https://tokens.bd/api/gateway/config
```

```json
{
  "openaiBaseUrl": "https://tokens.bd/v1",
  "anthropicBaseUrl": "https://tokens.bd"
}
```

## API key header-এ পাঠান

Key দুটো header-এর যেকোনো একটায় দিলেই চলে। আপনার client যেটা default-এ পাঠায়, সেটাই ব্যবহার করুন।

| Header          | Format                     | কারা পাঠায়                                                           |
| --------------- | -------------------------- | ---------------------------------------------------------------- |
| `Authorization` | `Bearer tok_live_your_key` | OpenAI SDKs, `ANTHROPIC_AUTH_TOKEN` দিয়ে Claude Code, বেশির ভাগ tool |
| `x-api-key`     | `tok_live_your_key`        | Anthropic SDKs                                                   |

দুটো header একসাথে এলে `Authorization: Bearer` header-টাই ধরা হয়। `Authorization` header-এ `Bearer` ছাড়া অন্য কোনো scheme থাকলে সেটা বাদ যায়, তখন gateway `x-api-key` খোঁজে।

:::code-tabs

```bash title="Bearer"
curl https://tokens.bd/v1/models \
  -H "Authorization: Bearer $TOKENS_API_KEY"
```

```bash title="x-api-key"
curl https://tokens.bd/v1/models \
  -H "x-api-key: $TOKENS_API_KEY"
```

:::

## Key-এর format

Key দেখতে `tok_live_` দিয়ে শুরু হয়, তারপর 48টা hexadecimal character। [Dashboard](/dashboard/keys)-এ key তৈরির সময় পুরো secret একবারই দেখানো হয়। আমরা শুধু hash রাখি, তাই হারিয়ে গেলে key ফেরত আনা যায় না; নতুন একটা তৈরি করে নিন। Key তৈরি, spend cap, allowed-model list আর rotation নিয়ে বিস্তারিত আছে [API keys](/docs/api-keys) পেজে।

## Key রাখুন environment variable-এ

Docs-এর সব উদাহরণে key পড়া হয় `TOKENS_API_KEY` থেকে:

```bash
export TOKENS_API_KEY="tok_live_your_key"
```

Windows PowerShell-এ:

```powershell
$env:TOKENS_API_KEY = "tok_live_your_key"
```

তারপর code-এ key সরাসরি না লিখে এভাবে পড়ে নিন:

:::code-tabs

```python title="Python"
import os
from openai import OpenAI

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

```typescript title="Node.js"
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://tokens.bd/v1",
  apiKey: process.env.TOKENS_API_KEY,
});
```

:::

:::warning[Key commit করবেন না]
Commit করা `.env`, config file বা notebook-এ key থাকা মানে key leak হয়ে যাওয়া। এই file-গুলো `.gitignore`-এ রাখুন। Key leak হয়ে গেলে Dashboard থেকে rotate করুন; পুরোনো secret সঙ্গে সঙ্গে কাজ করা বন্ধ করে দেয়।
:::

## শুধু server-side: browser থেকে call নয়

API-র response-এ CORS header থাকে না। তাই key ঠিক থাকলেও web page থেকে `fetch` করলে browser-এ সেটা fail করবে। এটা ইচ্ছা করেই করা: browser-এ key পাঠালে যে কেউ dev tools খুলে সেটা পড়ে ফেলতে পারে। Tokens-কে call করুন আপনার backend, serverless function, CLI বা coding agent থেকে, আর frontend সেই backend-এর সঙ্গে কথা বলুক।

## 401 আর 403-এর মানে

Authentication fail করলে standard error body আসে, সঙ্গে machine-readable একটা `code`:

```json
{
  "error": {
    "message": "Invalid API key.",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null,
    "request_id": "8f0c7a4e-2b1d-4c55-9a51-3f7e2d9b6c10"
  }
}
```

| Status | Code                         | মানে                                                                  | যা করবেন                                                                     |
| ------ | ---------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| 401    | `missing_api_key`            | `Authorization: Bearer` বা `x-api-key` কোনো header-ই আসেনি            | যে shell-এ tool চালাচ্ছেন সেখানে env var set আছে কিনা দেখুন                  |
| 401    | `invalid_api_key`            | Key-টা আমাদের দেওয়া কোনো key-র সঙ্গে মেলে না                           | key কাটা পড়েছে কিনা বা বাড়তি quote আছে কিনা দেখুন; key আবার copy করুন, নয়তো নতুন বানান |
| 403    | `key_inactive`               | Key revoke বা rotate করা হয়েছে                                       | এখনকার secret ব্যবহার করুন, নয়তো নতুন key বানান                              |
| 403    | `key_expired`                | Key-র expiry date পেরিয়ে গেছে                                        | নতুন key বানান                                                               |
| 403    | `account_suspended`          | অ্যাকাউন্ট suspend করা আছে                                            | [Support](/docs/support)-এর সঙ্গে যোগাযোগ করুন                                |
| 403    | `model_not_allowed_on_key`   | Key-তে allowed-model list আছে, আর তাতে এই model নেই                    | list-এর কোনো model নিন, নয়তো অন্য key ব্যবহার করুন                          |
| 403    | `monthly_spend_cap_exceeded` | Key-টা তার monthly spend cap-এ পৌঁছে গেছে                              | পরের মাস পর্যন্ত অপেক্ষা করুন, নয়তো অন্য key নিন                              |
| 403    | `tier_permission_denied`     | আপনার plan-এ এই model নেই, আর Wallet-এ ব্যালান্সও নেই                  | [plan ও Wallet](/docs/plans-and-wallet) পেজ দেখুন                          |

`upstream_auth_error` code-সহ 401 বা 403 আলাদা ব্যাপার। এর মানে upstream provider-এর কাছে gateway-র নিজের credential ফিরিয়ে দেওয়া হয়েছে, আপনারটা নয়। আপনার key ঠিকই আছে; একটু পরে আবার চেষ্টা করুন বা অন্য model নিন, আর Support-এ জানালে request id-টা সঙ্গে দিন।

Billing আর rate-limit error-সহ সব code-এর পুরো list আছে [errors](/docs/errors) পেজে। Key শুরু থেকে শেষ পর্যন্ত কাজ করছে কিনা যাচাই করতে [quickstart](/docs/quickstart)-এ এক লাইনের একটা test request আছে।

---
Page: https://tokens.bd/bn/docs/authentication