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.
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 (avmo_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,billingorviewer. 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 grantssso:manageor 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) |
Related
- Venom Cloud APIs overview: client keys and the
/v1surface your customers' requests use - Admin API: usage, budgets and spend:
customerbudgets and chargeback - Admin API: daemons, fleet and reliability: SLA targets and service credits