SumoRouter
SumoRouter Admin API

SumoRouter Admin API

Everything an admin can do in the SumoRouter dashboard, as a REST API: users and their balances, virtual (user) API keys, request logs, the model catalog and prices, finance reports and payments, analytics, coupons, the affiliate program, site settings, admin API keys and the audit log.

Authentication

Every request needs Authorization: Bearer <token>, where the token is either:

  • an admin API key (sk-admin-…), created in Admin → Admin API from a dashboard session. Keys can be read-only (only GET/HEAD allowed, anything else returns 403), can expire, can be limited to IP addresses / CIDR ranges (checked against the X-Real-IP header set by the reverse proxy; without it an IP-restricted key is refused), and are rate-limited to 120 requests per minute per key (429 beyond that). A key stops working when it is revoked or when its owner is disabled or no longer an admin. Admin API keys cannot manage admin API keys: the /api-keys routes require a dashboard session.
  • an admin dashboard session (the JWT the dashboard gets at sign-in). Admin sessions are only issued after two-factor authentication; sessions without 2FA are refused.

User API keys (sk-… without admin-) do not work here (they are rejected with 401), and admin API keys do not work on the AI endpoints (/v1/*).

Conventions

  • Money is integer nano-USD: 1 USD = 1_000_000_000 nano-USD (fields ending in _nano). Amounts ending in _idr are whole Indonesian Rupiah (top-ups are paid in IDR via QRIS).
  • Timestamps are RFC 3339 / ISO 8601 in UTC unless stated otherwise.
  • Paginated lists take limit and offset and return { "items": [...], "total": n } (plus extra counters on some endpoints). limit is clamped to 1..200; a negative offset is treated as 0.
  • Secrets in settings are never returned: responses carry a masked *_hint instead (e.g. sk-****-a1b2), or null when unset. On PUT, omitting a secret (or sending an empty string) keeps the stored value.
  • Errors use an OpenAI-style body: {"error": {"message", "type", "code"}}. Requests whose JSON body is malformed or misses a required field are rejected by the framework before the handler runs, with 400/415/422 and a plain-text body.
  • Every successful change (non-GET) is written to the audit log, with the admin API key id in details.admin_api_key when one was used. Request bodies of settings are never logged.

MCP server

The same admin API is also available to AI agents as an MCP server at /mcp (e.g. https://<your-domain>/mcp), using the Streamable HTTP transport (JSON responses, no SSE) and authenticated with the same Authorization: Bearer sk-admin-… header. Each MCP tool call is executed as a request to this REST API with the caller's key, so read-only keys, IP allow-lists, validation and the audit log apply identically. See the MCP guide for the tool list and client setup.

Tags
Users
List, create and edit users; suspend, credit, 2FA reset and per-user history.
Virtual keys
Every user's API keys in one list (never the secret).
Request logs
Request logs across all users. Prompt and response content are never stored.
Models
The model catalog synced from Sumopod, sell prices, capabilities and availability.
Reports & payments
Finance overview and the log of every top-up request.
Analytics
Platform-wide revenue, upstream cost, traffic and top models/users.
Coupons
Credit coupons users can redeem.
Affiliates
Referral program results and settings.
Settings
Site settings, one document per section: ai, payment, auth, limits, retention, branding, email and affiliate. Secrets are returned masked and kept when omitted on PUT.
Admin API keys
sk-admin-… keys for this API and the MCP server. These routes only accept a dashboard session (with 2FA); an admin API key gets 403.
Audit
The audit log of admin and user actions.
System
Information about the running build.