MSP mode and the partner portal
Manage many client organisations from one Venom Cloud org, with each client's consent, a ceiling role, scopes and an end date.
MSP mode lets a managed service provider (a partner, an agency, an internal platform team) work inside client organisations from its own org. Each client decides who gets in, with which role, which scopes and until when, and can take it back at any moment. Nothing calls out; every link and staff change is written to both organisations' audit logs.
Three pages:
| Page | Who | What |
|---|---|---|
/msp |
The partner's members (org:read) |
The portfolio: every client you may see, invites, linked orgs, staff per client, starter packs across clients, the billing roll-up as CSV. |
/msp/clients/{id} |
Partner owners, admins, billing members, and staff on that client | One client's health, requests and errors in 24 hours, the month's spend by day and model, budgets, daemons and the grant. |
/settings/msp |
The client (org:read; owners and admins change it) |
Accept an invite or make an offer, and for each partner: the grant, the staff who can enter, and Revoke. |
Link a client
Either side can start.
The partner invites. On /msp, an owner or admin creates an invite naming the access asked for. It returns a vmi_ token, shown once, valid once for 14 days. Send it to the client. An owner of the client pastes it on /settings/msp; a dry run first says who asks for what, what the partner will see and how to take it back. The owner then picks the role, scopes and end date (the partner's ask is the default) and accepts.
The client offers. On /settings/msp, an owner makes an offer with a role, scopes, an optional end, a note and optionally the one partner org that may claim it. It returns a vmo_ token, shown once, valid once for 14 days. A partner owner or admin pastes it on /msp, reads what it grants, and claims it. An unknown, used, expired, cancelled or other-partner offer answers the same "not found".
You own both orgs. "New client org" on /msp creates an org with you as owner and links it in one step.
There is at most one active link per pair of orgs, and an org never manages itself.
The grant
A grant is a ceiling role, a set of scopes and an optional end (access_expires_at).
| Ceiling role | Reads |
|---|---|
admin, developer, billing, viewer |
What that role reads. Never owner. |
| Scope | Allows changing |
|---|---|
members |
Invite, re-role and remove the client's members (never owners; never people who are members of the partner org) |
keys |
API keys |
billing |
Budgets, spend caps, plan, invoices |
daemons |
Enroll and manage daemons |
routing |
Routing |
providers |
Add and rotate provider keys (never read back) |
settings |
Organisation and content settings |
content |
Read logged prompts and responses |
No scopes means read-only. A staff member acts with the role's read permissions plus what the granted scopes name, never more than the role. No scope gives single sign-on settings or ownership. A refused action answers 403 with "the access this organisation granted your managed service does not include this".
The client's owner changes the role, scopes or end on /settings/msp at any time; staff above a lowered ceiling drop to the best role that fits, or lose access. A lapsed end is no access everywhere at once; set a new end (or none) to renew. A revoked link stays revoked: a new grant needs a new invite or offer.
Staff and working inside a client
On /msp, the partner's owners and admins assign staff per client, each with a role within the ceiling. Nobody reaches a client without a staff row on an active link, partner owners included.
Staff enter a client from the org switcher (or Open on /msp). The console re-issues the session for the client, shows a banner with the client's name, logo and colour, the partner and the role, and a way back. Every request re-checks the link, the staff row, partner membership and the partner's single sign-on rule, so a revocation, a lowered ceiling or a removed person takes effect on the next request.
Staff can be added to the client's teams, with the partner's name shown as a badge. They join as members; the client's owner decides whether they may be team admins with Their staff may be team admins under Change access on /settings/msp (off by default). Turning it off makes them members again, and ending a staffer's access takes them out of every team.
From inside a client, a staff session cannot manage links, accept invites or enter another org. API keys that staff create are ordinary keys and outlive console access: /settings/msp counts them, and Revoke can take them with it.
Portfolio and client view
/msp lists each active client's month spend, requests and errors in 24 hours, live and enrolled daemons, spend alerts in 7 days, open status incidents and a health word. Aggregates only. Owners, admins and billing members see every client; other members see the clients they are staff on. The CSV download is the month's billing roll-up.
Packs across clients previews or installs a starter pack in the checked clients, as your staff role in each (it needs org:manage there). Clients you can't install into are skipped with the reason.
/msp/clients/{id} shows only what the grant reads: sections it doesn't (usage, budgets, daemons) are empty. Every other case (no link, revoked, lapsed, another partner's client, your own org, a bad id) is the same "not found". Each view writes msp.client_viewed to the client's audit log, at most once an hour per person.
Provider keys stay sealed: no partner page or grant shows a provider key or its last characters beyond the hint members see.
Audit
Both orgs get msp.invite_created, msp.link_accepted, msp.link_created, msp.staff_added, msp.staff_role_changed, msp.staff_removed, msp.link_role_changed, msp.link_grant_changed, msp.link_revoked, msp.link_ended, msp.link_expired, msp.invite_cancelled, msp.offer_created, msp.offer_claimed, msp.offer_cancelled and msp.entered. A change a staff session makes in the client is recorded there under the partner's actor with via_msp, and mirrored to the partner's log as msp.client_action (no contents).
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| The client isn't in the org switcher | You are not staff on it, the link is revoked or lapsed. Ask a partner owner or admin to assign you; ask the client to renew the end date. |
| 403 "does not include this" | The grant lacks the scope. The client's owner adds it on /settings/msp. |
| Only an owner can accept | Accepting an invite and changing the grant are owner-only on the client side. |
| Invite or offer "not found" | Used, expired (14 days), cancelled, or bound to another partner. Make a new one. |