Management keys & webhooks

Manage keys and read usage from code with an irm- key, and get events on your own server.

When the work grows, some of the panel's work can move into code: a key per customer or per environment, reading usage and the balance, and hearing about events without checking the panel all the time.

Management keys

A management key starts with irm- and is not an API key (ir-): it cannot call models, but it can make API keys, read usage and see the balance.

  1. Only the account owner makes one: in the panel, Profile & security → Management keys. In an organization, the section shows only in the owner's own account.
  2. Give it a name and pick the least access you need.
  3. The key is shown in full only once. If you lose it, revoke it and make a new one.
LevelWhat it can do
Read only (read)GET requests only: the key and workspace lists, usage, the balance. Anything else gets 403 management_key_readonly.
Manage keys (write)Plus creating, changing, rotating and revoking API keys.
  • An account holds at most 5 active management keys; revoked ones do not count. A sixth gets 400 management_key_limit.
  • A management key can never make or revoke another management key; that is done only in the panel, signed in as the owner. So whoever gets hold of one cannot use it to mint another.
  • Revoking bites at once: the next request with that key gets 401 invalid_management_key. If the account is suspended, its management keys stop working too.
  • Each management key has a requests-per-minute cap that we set; past it, the answer is 429 rate_limit_exceeded.
  • An ir- key on these routes gets 401 invalid_management_key, and an irm- key cannot call models either.

The management API

All under https://iranrouter.com/provision, with the header Authorization: Bearer irm-…. Each route does what the panel does for the same account, with the same checks.

RouteLevelWhat it does
GET /provision/keysreadEvery API key of the account, with its workspace.
GET /provision/projectsreadThe workspaces, so you know where to make keys. Creating and changing workspaces stays in the panel.
POST /provision/projects/{id}/keyswriteMakes an API key in a workspace. name is required; the rest are the panel's own settings, allowed_ips, max_concurrent and byok_upstream_key_id included. The key's secret is in this answer only. An account holds at most 1000 usable keys; past that it is 400 key_limit_reached.
PATCH /provision/keys/{id}writeChanges a key: name, allowed_models, monthly_budget_rial, daily_budget_rial, daily_token_budget, billing_source (plan or credit), expires_in, rpm_limit and tpm_limit, max_concurrent (requests in flight, 1–1000), allowed_ips (IPs or ranges), org_owned (an organization key; owner and admins only), status (active or disabled) and byok_mode. A member cannot lift a cap an admin put on their key.
POST /provision/keys/{id}/rotatewriteA new secret, once, in the answer; the old one stops working at once.
DELETE /provision/keys/{id}writeRevokes the key, for good.
GET /provision/usagereadUsage rows; takes from, to, project_id, api_key_id, limit and offset. It reads a replica, so a request made a moment ago may show a few seconds later; two calls at once per account (a third is 429 analytics_busy), 15 s each (past that 400 analytics_too_heavy: narrow the range).
GET /provision/usage/summaryreadUsage totals; takes from, to and group_by, one of day, model, project, api_key or day_model.
GET /provision/creditsreadThe wallet balance.
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

Instead of asking every few minutes whether something happened, let us tell you: events are POSTed to your address. Webhooks are set per workspace.

Where to set them

  • In the panel, on the API keys page, choose Webhooks from that workspace's menu. Only the owner and the organization's admins can, and a management key cannot.
  • The address must be public https on port 443. localhost, private-network addresses and names that resolve to a private network are refused, and this is checked again at every delivery.
  • A workspace has at most 5 endpoints, and an account 25 in all (400 webhook_endpoint_cap and webhook_account_cap).
  • The signing secret (whsec_…) is shown only once, when you create the endpoint.
  • The money events (payment.verified, balance.low and plan.expiring) need billing access: the owner, or an admin while the owner has given admins billing access.
  • After creation, only on/off and the sampling rate can change. For another address or other events, make a new endpoint.

Events

EventWhendata
payment.verifiedA payment was verified and the wallet topped up.payment_id, amount_rial
key.suspendedOne of your API keys was suspended by us.api_key_id, key_prefix
plan.expiringYour plan is about to expire.plan, expires_at, days_left
balance.lowThe spendable balance fell below the alert threshold (at most once a day), or a key reached 80% of its monthly cap (once a month per key). It goes with the alert e-mail, so only for an account with a verified e-mail that has not turned that alert off in its profile.reason: wallet + available_rial | reason: key_budget + api_key_prefix, budget_pct, spend_mtd_rial, monthly_budget_rial
model.deprecatedA model you used in the last 30 days was deprecated.model, sunset_at, successor
model.price_droppedThe price of a model you used in the last 30 days dropped.model, drop_pct
generation.completedEvery request of this workspace, metadata only (below).generations

Each delivery is a POST with a JSON body shaped like this:

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 }
}

Verifying the signature

The signature is HMAC-SHA256 of the raw request body with the signing secret, in hex, prefixed with sha256=. Use the secret exactly as given, whsec_ included. Compute it over the raw bytes you received, before parsing, never over re-serialized JSON, and compare in constant time.

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));
}

Better: the V2 signature. A body captured on the way can be sent again at any time with the signature above. V2 signs the delivery id and the time too: HMAC-SHA256 of "delivery.timestamp.raw body" with the same secret. Refuse a delivery whose timestamp is more than five minutes from your clock, and since every retry carries the same X-IranRouter-Delivery, do each id's work once.

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

Delivery, retries and switching off

  • A 2xx answer means delivered. Anything else, a redirect (3xx) or no answer within 10 seconds included, is a failure. Each delivery is tried up to 5 times, each later than the last: one minute, five minutes, half an hour and two hours on, so an endpoint that is down for a few minutes misses nothing.
  • After 25 failed deliveries in a row (any success resets the count), the endpoint is switched off, with the reason beside it. Turn it back on once it is fixed; the count starts again.
  • The last 50 deliveries of each endpoint, with their status and error, are listed in the same Webhooks window.
  • An event may arrive twice. Answer 2xx quickly and do the heavy work afterwards.

The request stream (generation.completed)

The metadata of every request of this workspace, in batches of up to 500 per delivery; never the prompt or the answer. Each request carries:

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 (1 to 100, default 100) sets the share of requests sent. The pick is made from the request id, so a request is always either in or out.
  • It is best-effort: a request may arrive twice (de-duplicate on id), and an endpoint that falls far behind loses its oldest ones. Nothing is gathered for an endpoint while it is off, and this event's deliveries are dropped after three days, delivered or not.
  • The otlp format sends the same requests as OTLP/HTTP JSON spans, for your own monitoring tool's collector; the traceId is the request id. An otlp endpoint takes this event only.
  • A header your collector needs (usually its API key) can be stored with the endpoint; it is kept encrypted and never shown again.

Your own keys (BYOK) →