Whitelabel & Reseller Setups

Two technical patterns for putting Surplus behind your own product. Let Surplus provision and meter one key per end customer, or run your own gateway in front and call Surplus with a small pool of high-capacity keys.

The right pattern depends on one question: who owns per-customer isolation and billing? If you want Surplus to be the system of record for each downstream customer, use Pattern A. If your gateway already owns customer identity, quotas, and billing, use Pattern B.

Pattern A: a Surplus key per customer

Best when you want Surplus to hold each downstream customer's budget and usage. You create an organization, then use an admin key to mint one scoped buyer key per customer through the /v1/keys provisioning API. Each key carries its own scope, budget, and usage attribution, enforced on the backend. The organization remains the billing account: every key spends from one prepaid balance, and the per-key budget is what bounds a customer (see Isolation, budgets, and caps).

Admin keys (inf_admin_...)

An admin key is a management key. It mints, scopes, rotates, and revokes buyer keys through /v1/keys, scoped to its own workspace.

An organization owner or admin creates the admin key from the dashboard or an owner/admin session. Treat it like a root credential: anyone holding it can provision and revoke every customer key in the workspace.

The provisioning API (/v1/keys)

Full CRUD plus rotate over the workspace's keys. Every route requires the keys.manage capability, which an admin key holds. Every write here requires an Idempotency-Key header (create, update, rotate, and revoke alike); omitting it is a 400 idempotency_key_required, not a silent success.

POST /v1/keys
Authorization: Bearer inf_admin_xxx
Idempotency-Key: 9f8c1e2b-...     # required
{ "name": "customer-8842" }
# → { "id": "01JQ...", "key": "inf_...", "key_prefix": "inf_9f8c1e2b", "key_type": "buyer" }

POST /v1/keys
Authorization: Bearer inf_admin_xxx
Idempotency-Key: a1b2c3d4-...
{
  "name": "customer-8842",
  "scope": { "models": ["claude-opus-4.6", "gpt-5.4"], "min_discount_pct": 20 },
  "budget": { "limit_month_micro": 250000000 }   // 250 USD/month, in micro-USD
}

POST /v1/keys/{id}/rotate
Authorization: Bearer inf_admin_xxx
Idempotency-Key: c3d4e5f6-...     # required
{ "grace_hours": 24 }             # optional; 0 (default) revokes the old key at once
# → a NEW id + a NEW `key` secret; the old key is retired

DELETE /v1/keys/{id}
Authorization: Bearer inf_admin_xxx
Idempotency-Key: d4e5f6a7-...     # required

Isolation, budgets, and caps

• Isolation is per key, and it is enforced by scope plus budget, not by separate funds. Every key in the organization draws on the same prepaid balance, so what stops one customer spending another's money is the key's budget (hard_stop is on by default), not a wall between accounts. A key minted without a budget can spend the whole organization balance, so set one at mint time for every customer key. Usage is attributed per key regardless.
• Budgets nest. A key's budget sits inside its member, workspace, and organization budgets, and every enclosing scope must have room. See budgets and spend limits.
• Key caps are counts of active keys, not request-rate limits:

If you expect more than a few hundred concurrent customer keys, prefer Pattern B or contact us about a dedicated organization.

Pattern B: your gateway in front

This is the right model when your gateway already owns per-customer isolation, quotas, and billing. Surplus does not need to know your customers. You call it with a small pool of high-capacity buyer keys under one dedicated organization, and reconcile cost back to your own accounts.

Rate limits and throughput

Two independent limits apply. For a gateway pooling keys behind one address, the aggregate per-IP ceiling can bind first.

The per-IP rule has roughly the same average ceiling as one completion key, but it counts every request from an address regardless of how many keys or routes those requests use. A gateway calling Surplus from one NAT address therefore tops out near 1,200 requests per minute on average no matter how its traffic is split across keys.

So a high-volume integration scales on two axes, and you need both:

• Spread egress IPs. This is what actually lifts the binding ceiling for a gateway. Traffic split across N source addresses gets N times the per-IP allowance.
• Pool keys. Once you are past the per-IP ceiling, several keys lift the per-key ceiling the same way. Under a dedicated org you provision these through the admin key. Pooling keys behind a single IP buys you nothing.
• Plan high volume with us. Both ceilings are fixed guardrails rather than per-account tuning, so for sustained reseller traffic provision a dedicated organization and tell us your expected throughput and your egress addresses. We can then confirm upstream capacity and the per-IP allowance ahead of launch.

Beyond the rate limit, real throughput is bounded by your prepaid balance (a request is rejected if the balance cannot cover its estimated maximum cost) and upstream provider capacity for the models you route to. Requests are served by horizontally scaled fleets.

Automatic provider failover

You do not build failover yourself. The marketplace routes each request to the cheapest healthy seller for the model, marks a seller unhealthy on failure, and backs off, so traffic moves to the next seller automatically. You can also register your own provider keys as priority or fallback providers if you want your own capacity tried first or used as a safety net.

Reconciling Surplus cost against what you bill

Most requests expose their cost inline so you can attribute it to the downstream customer your gateway is billing. The inline figure is best-effort and wire-specific, so treat it as a fast path and the request log as the authority:

Use the inline figure for real-time margin where it is present, and reconcile against GET /v1/requests on a schedule. For a request whose cost never appeared inline (a stream without usage, or a charge not yet known), GET /v1/requests/{id} is the authoritative per-request record. Never infer a zero cost from a missing header or trailer.

Keep a balance buffer

Because a request is rejected when the balance cannot cover its estimated maximum, keep a buffer above your steady-state burn and enable automatic top-up so a busy hour never drains you to zero mid-stream.

A dedicated org for volume

There is no separate technical "reseller tier." Capacity is architectural (horizontally scaled fleets) and everyone runs against the same guardrails: the per-key and per-IP rate limits above, and your prepaid balance. There is no per-account throttle to raise, so a reseller is not given a bigger bucket than anyone else. What a high-volume reseller gets is a dedicated organization so usage, billing, and keys are cleanly separated from everyone else, plus a direct line to plan capacity and the per-IP allowance before launch.

Create one yourself in the dashboard: open the organization menu at the top of the sidebar and choose New organization. If you expect sustained volume, tell us your expected throughput and the models you plan to route through the Enterprise contact form or support@surplusintelligence.ai, so we can plan capacity.

Reselling and the Terms

Reselling is allowed under §8 of the Terms of Service, on the conditions it sets out.

Related