کلید مدیریتی و Webhook
مدیریت کلیدها و خواندن مصرف از کد با کلید irm-، و گرفتن رویدادها روی سرور خودتان.
وقتی کار بزرگ میشود، بخشی از کار پنل را میشود به کد سپرد: ساختن کلید برای هر مشتری یا هر محیط، خواندن مصرف و موجودی، و خبر گرفتن از رویدادها بدون سر زدن مداوم به پنل.
کلید مدیریتی
کلید مدیریتی با irm- شروع میشود و با کلید API (ir-) فرق دارد: مدل صدا نمیزند، ولی میتواند کلید API بسازد، مصرف را بخواند و موجودی را ببیند.
- فقط مالک حساب آن را میسازد: در پنل، «پروفایل و امنیت» ← «کلیدهای مدیریتی». در یک سازمان، این بخش فقط در حساب خود مالک دیده میشود.
- یک نام بگذارید و کمترین سطح دسترسیای را که لازم دارید انتخاب کنید.
- کلید فقط همان یک بار کامل نشان داده میشود. اگر گم شد، باطلش کنید و کلید تازه بسازید.
| سطح | چه میتواند |
|---|---|
| فقط خواندن (read) | فقط درخواستهای GET: فهرست کلیدها و Workspaceها، مصرف، موجودی. هر درخواست دیگری ۴۰۳ management_key_readonly میگیرد. |
| مدیریت کلیدها (write) | بهعلاوهٔ ساختن، تغییر، چرخاندن و باطل کردن کلیدهای API. |
- هر حساب حداکثر ۵ کلید مدیریتی فعال دارد؛ کلیدهای باطلشده حساب نمیشوند. ششمی ۴۰۰ management_key_limit میگیرد.
- کلید مدیریتی هیچوقت نمیتواند کلید مدیریتی دیگری بسازد یا باطل کند؛ این کار فقط از پنل و با ورود خود مالک انجام میشود. پس کسی که یکی را به دست بیاورد، با آن کلید مدیریتی تازهای نمیسازد.
- باطل کردن همان لحظه اثر دارد: درخواست بعدی با آن کلید ۴۰۱ invalid_management_key میگیرد. اگر حساب معلق شود، کلیدهای مدیریتیاش هم کار نمیکنند.
- هر کلید مدیریتی در دقیقه سقف درخواستی دارد که ما تعیین میکنیم؛ بیشتر از آن ۴۲۹ rate_limit_exceeded است.
- کلید ir- روی این مسیرها ۴۰۱ invalid_management_key میگیرد، و کلید irm- هم مدل صدا نمیزند.
مسیرهای API مدیریتی
همه زیر https://iranrouter.com/provision، با هدر Authorization: Bearer irm-…. هر مسیر همان کاری را میکند که پنل برای همان حساب میکند، با همان بررسیها.
| مسیر | سطح | چه میکند |
|---|---|---|
GET /provision/keys | read | همهٔ کلیدهای API حساب، با Workspace هرکدام. |
GET /provision/projects | read | Workspaceها، تا بدانید کلید را کجا بسازید. ساختن و تغییر Workspace فقط از پنل است. |
POST /provision/projects/{id}/keys | write | ساختن کلید API در یک Workspace. name لازم است؛ بقیه همان تنظیمهای پنلاند، allowed_ips، max_concurrent و byok_upstream_key_id هم. رمز کلید فقط در همین پاسخ میآید. هر حساب حداکثر ۱۰۰۰ کلید ِ قابلاستفاده دارد؛ بیشتر از آن ۴۰۰ key_limit_reached است. |
PATCH /provision/keys/{id} | write | تغییر کلید: name، allowed_models، monthly_budget_rial، daily_budget_rial، daily_token_budget، billing_source (plan یا credit)، expires_in، rpm_limit و tpm_limit، max_concurrent (درخواست همزمان، ۱ تا ۱۰۰۰)، allowed_ips (فهرست IP یا بازه)، org_owned (کلید سازمانی؛ فقط مالک و مدیر)، status (active یا disabled) و byok_mode. یک عضو سقفی را که مدیر روی کلیدش گذاشته برنمیدارد. |
POST /provision/keys/{id}/rotate | write | رمز تازه، فقط یک بار در پاسخ؛ رمز قبلی همان لحظه از کار میافتد. |
DELETE /provision/keys/{id} | write | باطل کردن کلید، برای همیشه. |
GET /provision/usage | read | سطرهای مصرف؛ با from، to، project_id، api_key_id، limit و offset. از نسخهٔ خواندنی میخواند، پس درخواستی که همین الان رفته ممکن است چند ثانیه بعد بیاید؛ هر حساب دو فراخوانی ِ همزمان (سومی ۴۲۹ analytics_busy) و هرکدام ۱۵ ثانیه (بیشتر: ۴۰۰ analytics_too_heavy؛ بازه را کوتاه کنید). |
GET /provision/usage/summary | read | جمع مصرف؛ با from، to و group_by یکی از day، model، project، api_key یا day_model. |
GET /provision/credits | read | موجودی کیف پول. |
# a key for one customer, with a daily cap curl https://iranrouter.com/provision/projects/<workspace-id>/keys \ -H "Authorization: Bearer irm-..." \ -H "Content-Type: application/json" \ -d '{"name": "customer-42", "billing_source": "credit", "daily_budget_rial": 500000}' # this month's spend, by model curl "https://iranrouter.com/provision/usage/summary?from=2026-11-01&group_by=model" \ -H "Authorization: Bearer irm-..."
Webhook
بهجای اینکه هر چند دقیقه بپرسید چیزی شده یا نه، بگذارید ما خبر بدهیم: رویدادها با POST به آدرس شما فرستاده میشوند. Webhook برای هر Workspace جدا تعریف میشود.
کجا تعریفشان کنم
- در پنل، صفحهٔ «کلیدهای API»، از منوی همان Workspace گزینهٔ «Webhookها». فقط مالک و ادمینهای سازمان این کار را میکنند، و با کلید مدیریتی نمیشود.
- آدرس باید https عمومی روی پورت ۴۴۳ باشد. localhost، آدرسهای شبکهٔ داخلی و نامهایی که به شبکهٔ داخلی میرسند پذیرفته نمیشوند، و این در هر تحویل دوباره بررسی میشود.
- هر Workspace حداکثر ۵ endpoint دارد و هر حساب روی هم ۲۵ (۴۰۰ webhook_endpoint_cap و webhook_account_cap).
- کلید امضا (whsec_…) فقط همان یک بار، هنگام ساختن، نشان داده میشود.
- رویدادهای مالی (payment.verified، balance.low و plan.expiring) را فقط کسی میتواند بگیرد که دسترسی مالی دارد: مالک، یا ادمین وقتی مالک دسترسی مالی را به ادمینها داده است.
- بعد از ساختن، فقط روشن و خاموش کردن و درصد نمونهبرداری عوض میشود. برای آدرس یا رویدادهای دیگر، endpoint تازه بسازید.
رویدادها
| رویداد | کِی | data |
|---|---|---|
payment.verified | یک پرداخت تأیید و کیف پول شارژ شد. | payment_id, amount_rial |
key.suspended | یکی از کلیدهای API از طرف ما معلق شد. | api_key_id, key_prefix |
plan.expiring | پلن رو به انقضاست. | plan, expires_at, days_left |
balance.low | موجودی قابل خرج از آستانهٔ هشدار پایین رفت (حداکثر روزی یک بار)، یا یک کلید به ۸۰٪ سقف ماهانهاش رسید (ماهی یک بار برای هر کلید). همراه ایمیل هشدار میرود، پس فقط برای حسابی که ایمیل تأییدشده دارد و این هشدار را در پروفایل خاموش نکرده. | reason: wallet + available_rial | reason: key_budget + api_key_prefix, budget_pct, spend_mtd_rial, monthly_budget_rial |
model.deprecated | مدلی که در ۳۰ روز گذشته استفاده کردهاید از رده خارج شد. | model, sunset_at, successor |
model.price_dropped | قیمت مدلی که در ۳۰ روز گذشته استفاده کردهاید کم شد. | model, drop_pct |
generation.completed | هر درخواست این Workspace، فقط متادیتا (پایینتر). | generations |
هر تحویل یک POST است با بدنهٔ JSON به این شکل:
POST /your/endpoint
Content-Type: application/json
X-IranRouter-Event: payment.verified
X-IranRouter-Signature: sha256=5f0c…
X-IranRouter-Delivery: 8d1e…
X-IranRouter-Timestamp: 1795075800
X-IranRouter-Signature-V2: t=1795075800,v1=a3b9…
{
"event": "payment.verified",
"created_at": "2026-11-11T08:30:00.000Z",
"data": { "payment_id": "…", "amount_rial": 5000000 }
}بررسی امضا
امضا HMAC-SHA256 بدنهٔ خام درخواست است با کلید امضا، بهصورت hex و با پیشوند sha256=. کلید امضا را همانطور که هست، با whsec_، به کار ببرید. روی بایتهای خامی که رسیده حساب کنید، پیش از parse، نه روی JSONی که دوباره ساختهاید، و با مقایسهٔ زمانثابت بسنجید.
import hashlib, hmac def verified(raw_body: bytes, header: str, secret: str) -> bool: want = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest() return hmac.compare_digest(want, header or "")
import crypto from "node:crypto"; function verified(rawBody, header, secret) { const want = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex"); return typeof header === "string" && header.length === want.length && crypto.timingSafeEqual(Buffer.from(want), Buffer.from(header)); }
بهتر: امضای V2. بدنهای که کسی در راه گرفته باشد با امضای بالا هر وقت دوباره فرستاده میشود. V2 شناسهٔ تحویل و زمان را هم امضا میکند: HMAC-SHA256 ِ «شناسهٔ تحویل.زمان.بدنهٔ خام» با همان کلید. تحویلی را که زمانش بیش از پنج دقیقه با ساعت شما فاصله دارد رد کنید، و چون هر تلاش دوباره همان X-IranRouter-Delivery را دارد، کار هر شناسه را یک بار انجام دهید.
import hashlib, hmac, time def verified_v2(raw_body: bytes, headers, secret: str, seen: set) -> bool: delivery = headers.get("X-IranRouter-Delivery", "") parts = dict(p.split("=", 1) for p in headers.get("X-IranRouter-Signature-V2", "").split(",") if "=" in p) ts = parts.get("t", "") if not ts.isdigit() or abs(time.time() - int(ts)) > 300 or delivery in seen: return False signed = f"{delivery}.{ts}.".encode() + raw_body want = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest() if not hmac.compare_digest(want, parts.get("v1", "")): return False seen.add(delivery) return True
تحویل، تلاش دوباره و خاموش شدن
- پاسخ 2xx یعنی تحویل شد. هر چیز دیگر، از جمله redirect (3xx) یا نرسیدن پاسخ در ۱۰ ثانیه، ناموفق است. هر تحویل تا ۵ بار امتحان میشود، هر بار دیرتر از قبل: یک دقیقه، پنج دقیقه، نیم ساعت و دو ساعت بعد؛ پس endpointی که چند دقیقه پایین است رویدادی از دست نمیدهد.
- پس از ۲۵ تحویل ناموفق پشت سر هم (هر تحویل موفق شمارش را صفر میکند)، endpoint خاموش میشود و دلیلش کنارش نوشته میشود. بعد از رفع مشکل روشنش کنید؛ شمارش از صفر شروع میشود.
- ۵۰ تحویل آخر هر endpoint، با وضعیت و خطایش، در همان پنجرهٔ Webhookها دیده میشود.
- ممکن است یک رویداد دو بار برسد. سریع 2xx بدهید و کار سنگین را بعد انجام دهید.
پخش درخواستها (generation.completed)
متادیتای هر درخواست این Workspace، دستهای و تا ۵۰۰ درخواست در هر تحویل؛ هرگز متن prompt یا پاسخ. فیلدهای هر درخواست:
{
"event": "generation.completed",
"created_at": "…",
"data": { "generations": [ {
"id": "…", "created_at": "…", "model": "deepseek/deepseek-v4-flash",
"api_key_id": "…", "workspace_id": "…", "status": "success", "error_code": null, "stream": true,
"input_tokens": 24, "output_tokens": 108, "cached_input_tokens": 0, "reasoning_tokens": 0,
"web_searches": 0, "charge_rial": 1840, "ttft_ms": 412, "latency_ms": 2210, "retries": 0,
"finish_reason": "stop", "session_id": null, "client": null, "app": null, "api_skin": null,
"guardrail_action": null
} ] }
}- sample_pct (۱ تا ۱۰۰، پیشفرض ۱۰۰) میگوید چند درصد درخواستها فرستاده شوند. انتخاب از روی شناسهٔ درخواست است، پس یک درخواست همیشه یا هست یا نیست.
- best-effort است: ممکن است یک درخواست دو بار برسد (روی id یکتا کنید)، و endpointی که خیلی عقب بماند قدیمیترینها را از دست میدهد. وقتی endpoint خاموش است چیزی برایش جمع نمیشود، و تحویلهای این رویداد بعد از سه روز پاک میشوند، رسیده یا نرسیده.
- قالب otlp همین درخواستها را بهشکل spanهای OTLP/HTTP JSON برای collector ابزار مانیتورینگ خودتان میفرستد؛ traceId همان شناسهٔ درخواست است. endpoint با قالب otlp فقط همین رویداد را میگیرد.
- هدری را که collector میخواهد (معمولاً کلید API آن) میشود کنار endpoint گذاشت؛ رمزشده ذخیره میشود و دیگر نشان داده نمیشود.