---
title: MSP mode and the partner portal
description: Manage many client organisations from one Venom Cloud org, with each client's consent, a ceiling role, scopes and an end date.
section: cloud
order: 82
audience: [operator]
sources: [services/nodejs-cloud/app/(console)/(shell)/msp, services/nodejs-cloud/app/(console)/(shell)/settings/msp, services/nodejs-cloud/lib/msp, services/nodejs-cloud/components/msp]
features: [cloud.console-msp]
---

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 {#link}

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 {#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 {#staff}

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

`/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 {#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 {#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. |

## Related

- [Customers](/docs/cloud/console-customers.md): reselling to customers instead of managing their orgs.
- [Settings](/docs/cloud/console-settings.md): members, single sign-on and the audit log.
- The `/api/admin/v1/msp` routes are in this section's API pages ([overview](/docs/cloud.md)).
