کلید مدیریتی و Webhook

مدیریت کلیدها و خواندن مصرف از کد با کلید irm-، و گرفتن رویدادها روی سرور خودتان.

وقتی کار بزرگ می‌شود، بخشی از کار پنل را می‌شود به کد سپرد: ساختن کلید برای هر مشتری یا هر محیط، خواندن مصرف و موجودی، و خبر گرفتن از رویدادها بدون سر زدن مداوم به پنل.

کلید مدیریتی

کلید مدیریتی با irm- شروع می‌شود و با کلید API (ir-) فرق دارد: مدل صدا نمی‌زند، ولی می‌تواند کلید API بسازد، مصرف را بخواند و موجودی را ببیند.

  1. فقط مالک حساب آن را می‌سازد: در پنل، «پروفایل و امنیت» ← «کلیدهای مدیریتی». در یک سازمان، این بخش فقط در حساب خود مالک دیده می‌شود.
  2. یک نام بگذارید و کمترین سطح دسترسی‌ای را که لازم دارید انتخاب کنید.
  3. کلید فقط همان یک بار کامل نشان داده می‌شود. اگر گم شد، باطلش کنید و کلید تازه بسازید.
سطحچه می‌تواند
فقط خواندن (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/keysreadهمهٔ کلیدهای API حساب، با Workspace هرکدام.
GET /provision/projectsreadWorkspaceها، تا بدانید کلید را کجا بسازید. ساختن و تغییر Workspace فقط از پنل است.
POST /provision/projects/{id}/keyswriteساختن کلید 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}/rotatewriteرمز تازه، فقط یک بار در پاسخ؛ رمز قبلی همان لحظه از کار می‌افتد.
DELETE /provision/keys/{id}writeباطل کردن کلید، برای همیشه.
GET /provision/usagereadسطرهای مصرف؛ با from، to، project_id، api_key_id، limit و offset. از نسخهٔ خواندنی می‌خواند، پس درخواستی که همین الان رفته ممکن است چند ثانیه بعد بیاید؛ هر حساب دو فراخوانی ِ هم‌زمان (سومی ۴۲۹ analytics_busy) و هرکدام ۱۵ ثانیه (بیشتر: ۴۰۰ analytics_too_heavy؛ بازه را کوتاه کنید).
GET /provision/usage/summaryreadجمع مصرف؛ با from، to و group_by یکی از day، model، project، api_key یا day_model.
GET /provision/creditsreadموجودی کیف پول.
Shell
# 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 به این شکل:

HTTP
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ی که دوباره ساخته‌اید، و با مقایسهٔ زمان‌ثابت بسنجید.

Python
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 "")
Node.js
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 را دارد، کار هر شناسه را یک بار انجام دهید.

Python
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 یا پاسخ. فیلدهای هر درخواست:

JSON
{
  "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 گذاشت؛ رمزشده ذخیره می‌شود و دیگر نشان داده نمی‌شود.

کلید اختصاصی (BYOK) ←