---
title: "Admin API: customers and MSP"
description: 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.
section: cloud
order: 360
audience: [builder, operator, agent]
sources: [services/nodejs-cloud/app/api/admin/v1/customers, services/nodejs-cloud/app/api/admin/v1/customer-branding, services/nodejs-cloud/app/api/admin/v1/customer-invoices, services/nodejs-cloud/app/api/admin/v1/msp, services/nodejs-cloud/lib/customers, services/nodejs-cloud/lib/msp, docs/cloud-mesh.md]
features: [cloud.api-admin-customers, cloud.api-admin-customer-branding, cloud.api-admin-customer-invoices, cloud.api-admin-msp]
---

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](/docs/cloud/api-overview.md#admin-credentials)). Customer
routes need `billing:read` to read and `billing:manage` to change (owners and the billing role). Errors follow
[the common shape](/docs/cloud/api-overview.md#errors).

## Worked example: a customer and its key {#example}

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:

```bash
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:

```ts
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 {#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 {#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}

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](/docs/cloud/api-admin-fleet.md#sla)).

| 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](/docs/cloud/api-webhooks.md#customer-stripe)).

## MSP mode {#msp}

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](/docs/cloud/teams.md#managed-service-staff); 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 {#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 {#related}

- [Venom Cloud APIs overview](/docs/cloud/api-overview.md): client keys and the `/v1` surface your customers' requests use
- [Admin API: usage, budgets and spend](/docs/cloud/api-admin-spend.md): `customer` budgets and chargeback
- [Admin API: daemons, fleet and reliability](/docs/cloud/api-admin-fleet.md#sla): SLA targets and service credits
