Skip to content
Docs menu

Admin API: customers and MSP

Resell Venom Cloud to your own customers with per-customer keys, limits, prices, budgets, invoices and a branded usage portal, or manage client orgs as a managed service provider, over /api/admin/v1.

View .md

Two ways to put Venom Cloud under someone else's name:

  • Customers are for an app that resells AI to its own users. A collections SaaS that drafts dunning letters for each of its client companies is the typical case: each client company becomes a customer of your org, with its own vck_ keys, rate limits, model list, price rule, monthly budget, invoices and a read-only usage page. Your customers never get a Venom account.
  • MSP mode is for a managed service provider that runs other organisations' Venom Cloud orgs. Each client org stays its own org and grants the MSP a role, with consent on both sides.

Every route takes an admin credential (who can use the admin API). Customer routes need billing:read to read and billing:manage to change (owners and the billing role). Errors follow the common shape.

Worked example: a customer and its key

Your app signs up a new client company, "Acme Recoveries". Create it as a customer with a 30 % markup, a monthly budget and a model list, then mint the key your backend uses for Acme's requests:

export VENOM_CLOUD=https://cloud.usevenom.dev
export ADMIN="Authorization: Bearer $VENOM_CLOUD_ADMIN_TOKEN"

# 1. The customer
curl -s "$VENOM_CLOUD/api/admin/v1/customers" -H "$ADMIN" -H "Content-Type: application/json" -d '{
  "name": "Acme Recoveries",
  "email": "billing@acme.example.com",
  "external_ref": "tenant_8812",
  "currency": "EUR",
  "fx_rate": 0.92,
  "pricing": {"kind": "markup", "percent": 30},
  "rpm": 120,
  "allowed_models": ["venom-auto", "gpt-4.1-mini"],
  "monthly_budget": 400
}'
# → {"id": "0193…", "name": "Acme Recoveries", "status": "active", …, "budget": {…}}

# 2. A key for it (the secret is in "key", shown once)
curl -s "$VENOM_CLOUD/api/admin/v1/customers/<customer id>/keys" -H "$ADMIN" \
  -H "Content-Type: application/json" -d '{"name": "production"}'
# → {"id": "…", "customer_id": "…", "name": "Acme Recoveries: production", "prefix": "vck_AbCd", "key": "vck_…"}

# 3. A private usage page you can link from your app
curl -s -X POST "$VENOM_CLOUD/api/admin/v1/customers/<customer id>/portal" -H "$ADMIN" \
  -H "Content-Type: application/json" -d '{}'
# → {"token": "vcp_…", "path": "/portal/vcp_…"}

The same in TypeScript, as your app's sign-up handler might do it:

const base = "https://cloud.usevenom.dev/api/admin/v1";
const headers = { Authorization: `Bearer ${process.env.VENOM_CLOUD_ADMIN_TOKEN}`, "Content-Type": "application/json" };

async function onboard(tenant: { id: string; name: string; email: string }) {
  const customer = await fetch(`${base}/customers`, {
    method: "POST",
    headers,
    body: JSON.stringify({ name: tenant.name, email: tenant.email, external_ref: tenant.id, pricing: { kind: "markup", percent: 30 } }),
  }).then((r) => r.json());
  const key = await fetch(`${base}/customers/${customer.id}/keys`, { method: "POST", headers, body: JSON.stringify({ name: "production" }) }).then((r) => r.json());
  return { customerId: customer.id, apiKey: key.key }; // store the key in your own secret store
}

Requests made with the customer's key work like any client key on /v1, with three differences: the customer's rpm, tpm and allowed_models replace the key's own; spend counts against the customer's budget; and while the customer is suspended or archived the key answers 403 customer_inactive. Your end users never see Venom: your backend holds the key.

Customers

Route Permission What it does
GET /api/admin/v1/customers billing:read Every customer with the month's usage at cost and at its price, the org's key groups and branding. ?month=YYYY-MM
POST /api/admin/v1/customers billing:manage Create one (fields below). Audited customer.created
GET /api/admin/v1/customers/{id} billing:read One customer, its keys, budget and the month's usage per model and day. ?month=YYYY-MM. Another org's id answers 404
PATCH /api/admin/v1/customers/{id} billing:manage Change name, email, external_ref, status (active or suspended), fx_rate, pricing, rpm, tpm, allowed_models, notes, monthly_budget. The currency is fixed. Audited
POST /api/admin/v1/customers/{id}/archive billing:manage Revoke its keys and portal link and drop its budget; its bookings are kept. Audited customer.archived
POST /api/admin/v1/customers/{id}/keys billing:manage {name, expires_at?}: a vck_ key, shown once. Its name is <customer name>: <name>. Audited customer.key_created and key.create
DELETE /api/admin/v1/customers/{id}/keys/{keyId} billing:manage Revoke one of its keys. Audited customer.key_revoked
POST /api/admin/v1/customers/{id}/portal billing:manage A new private read-only link to the customer's usage page (/portal/vcp_…, shown once; the old one stops working). {revoke: true} removes the link

Customer fields:

Field Type Default Rule
name string required at most 120 characters, unique in the org (case-insensitive)
email, external_ref, notes string none your own references; external_ref at most 120, notes at most 2,000
team_id uuid the org's first key group the key group the customer's keys live in (the API keeps the name team)
currency string USD USD, EUR, GBP, CAD, AUD, NZD, CHF, SEK, NOK, DKK, PLN, CZK, SGD, HKD, INR, BRL, MXN, ZAR, AED, ILS, JPY, KRW
fx_rate number 1 units of the customer's currency one US dollar buys; fixed per customer, not live
pricing object {kind: "markup", percent: 20} the price rule, below
rpm, tpm integer none replace the limits of the customer's keys
allowed_models string[] none (all) replaces the model list of the customer's keys
monthly_budget number none in the customer's currency, 0 to 10,000,000; a hard monthly cap (a customer budget)

Price rules (pricing):

kind Fields The customer pays
markup percent (0 to 1,000) cost × (1 + percent / 100), converted at fx_rate
price_list models: {"<model>": {input, output, cached?}} per 1M tokens in the customer's currency (at most 200 models), other_percent the list price; a model not on the list at other_percent over cost
flat monthly_fee, included, overage_percent a monthly fee that includes included worth of usage; usage past it at overage_percent over cost

An org has at most 1,000 customers and a customer at most 25 live keys (409 too_many_customers, 409 too_many_keys). An archived customer answers 409 archived; a new key for a suspended one answers 409 customer_inactive.

Branding

What your customers see on their usage page and invoices.

Route Permission What it does
GET /api/admin/v1/customer-branding billing:read {display_name, support_email, accent, logo}
PUT /api/admin/v1/customer-branding billing:manage Any of display_name (at most 120), support_email, accent (a colour like #2f6feb), logo (base64 PNG, JPEG or WebP, at most 100 KB; "" removes it). Audited customers.branding

Customer invoices

Invoices are drafted from a month's bookings at each customer's price. You approve a draft (it gets its number), then send it through your own Stripe account or mark it paid by hand. Approved credits from missed SLAs appear as negative lines (SLA targets).

Route Permission What it does
GET /api/admin/v1/customer-invoices billing:read The org's invoices. ?month=YYYY-MM, ?state=draft|open|overdue|paid|void
GET /api/admin/v1/customer-invoices/{id} billing:read One invoice with its lines, totals, cost and Stripe progress
POST /api/admin/v1/customer-invoices/generate billing:manage {month, customer_id?}: drafts from the month's bookings for every customer or one. A draft is rebuilt, an approved invoice kept. Audited customer_invoice.generated
POST /api/admin/v1/customer-invoices/{id}/{action} billing:manage {action} is approve (numbers the draft), send (through your Stripe; safe to retry), paid (by hand) or void. Each audited
GET /api/admin/v1/customer-invoices/export billing:read ?month=YYYY-MM[&drafts=1]: the month's invoices as CSV, a row per line plus tax and total. Audited customer_invoice.exported
GET /api/admin/v1/customer-invoices/settings billing:read Tax, payment terms, numbering, footer, and whether your Stripe is connected
PUT /api/admin/v1/customer-invoices/settings billing:manage Any of tax_pct (0 to 100, default 0), tax_label (1 to 40 characters, default Tax), due_days (default 30), number_prefix (default INV), footer
PUT /api/admin/v1/customer-invoices/stripe billing:manage {api_key, webhook_secret}: connect your own Stripe account. Checked with one call, both sealed in the vault. Audited
DELETE /api/admin/v1/customer-invoices/stripe billing:manage Disconnect it. Audited

Stripe reports payment back to /api/integrations/stripe/{tenant}/webhook (see Incoming webhooks).

MSP mode

An MSP org manages client orgs through staff it assigns per client. Rules that hold everywhere:

  • A link exists only by consent. Either the MSP sends an invite (a vmi_ token, shown once, valid 14 days) that an owner of the client accepts, choosing the ceiling role; or the client's owner offers access (a vmo_ token, optionally for one named partner) that the partner's owner or admin claims; or an owner of both orgs links them.
  • The ceiling is never owner: admin, developer, billing or viewer. An offer can add scopes, each granting writes on top of the role's reads: members, keys, billing, daemons, routing, providers, settings, content. No scope grants sso:manage or ownership.
  • Nobody reaches a client without a staff row on an active link, MSP owners included. Access is re-checked on every request, so a revocation ends it at once.
  • An MSP session never manages links. Every link and staff change is written to both orgs' audit logs, and every write an MSP session makes in a client carries the actor console:msp:<msp>:<who>.

Routes on the MSP's side:

Route Permission What it does
GET /api/admin/v1/msp org:read Client links, invites and staff (members who are not managers see the clients they are staff on)
POST /api/admin/v1/msp/invites org:manage {role?, note?}: an invite for a client's owner (default ceiling admin); the vmi_ token is shown once
POST /api/admin/v1/msp/links org:manage here, owner there {client_tenant_id, role?}: link an org you also own, with you as its first staff member
DELETE /api/admin/v1/msp/links/{id} org:manage Cancel an invite or end a client link; staff lose access at once
PUT /api/admin/v1/msp/links/{id}/staff org:manage {uid, role}: assign an MSP member to a client within its ceiling or change their role; role: null removes them
POST /api/admin/v1/msp/claim owner or admin {token, dry_run?}: read (dry_run: true) or claim a client's vmo_ offer. An offer made for another org answers 404
GET /api/admin/v1/msp/portfolio org:read Each active client's spend, requests, errors, daemons and alerts, and totals. ?month=YYYY-MM; ?format=csv is the month's billing roll-up
GET /api/admin/v1/msp/clients/{id} staff on the client One client's usage, spend, budgets, daemons and health within its grant. ?month=YYYY-MM. Without a live link every id answers 404. Each view is written to the client's audit log
POST /api/admin/v1/msp/apply your staff role in each client {pack, clients, dry_run?, budget_usd?}: preview or install a starter pack in several clients

Routes on the client's side:

Route Permission What it does
POST /api/admin/v1/msp/accept owner {token, role?, dry_run?}: read (dry_run: true) or accept an MSP's vmi_ invite, choosing the ceiling
POST /api/admin/v1/msp/managed/offers owner {role?, scopes?, expires_at?, note?, partner?}: offer access (default role viewer); the vmo_ token is shown once. expires_at at most 3,650 days ahead
GET /api/admin/v1/msp/managed org:read The managed services you let in, their ceilings and staff
PATCH /api/admin/v1/msp/managed/{id} owner {role?, scopes?, expires_at?, team_admins?}: change the grant; staff above a lowered ceiling drop to fit. team_admins (default false) lets the partner's staff be admins of the client's teams; turning it off makes them members
DELETE /api/admin/v1/msp/managed/{id} members:manage Revoke the managed service (or cancel an offer)
DELETE /api/admin/v1/msp/managed/{id}/staff/{uid} members:manage Take one MSP staff member's access away

None of the client-side routes work from an MSP session. An MSP has at most 500 links and a link at most 50 staff.

Errors

Status code When
400 invalid_request a field out of range or unknown (currency on PATCH), a token of the wrong shape, a staff role above the ceiling
403 forbidden the role lacks the permission (customers need billing:manage to change), the MSP grant does not include it, the MSP access ended
404 not_found another org's customer, invoice or link; an unknown or foreign offer
409 conflict, archived, customer_inactive, too_many_customers, too_many_keys, no_team a duplicate name, an archived or suspended customer, a cap reached, an org with no team
409 vault_not_configured connecting Stripe on a deployment without a vault key (VENOM_VAULT_KEYS)