+ ))}
)}
@@ -274,6 +340,3 @@ function NavigationGroup({ group, className, tableOfContents }) {
)
}
-
-
-
diff --git a/src/pages/ipa/guides/authentication.mdx b/src/pages/ipa/guides/authentication.mdx
index da8b92b6..2ac4a209 100644
--- a/src/pages/ipa/guides/authentication.mdx
+++ b/src/pages/ipa/guides/authentication.mdx
@@ -19,7 +19,7 @@ Always keep your token safe and reset it if you suspect it has been compromised.
## Using personal access tokens
-When establishing a connection using [PATs](/manage/public-api), you will need your access token — you can create one in the [NetBird dashboard](https://app.netbird.io/users) under User settings. It is recommended to use [service users](/manage/public-api) for all organization wide flows calling the API. Here's how to add the token to the request header using cURL:
+When establishing a connection using [PATs](/manage/public-api), you will need your access token — you can create one in the [NetBird dashboard](https://app.netbird.io/users) under User settings. It is recommended to use [service users](/manage/public-api) for all organization wide flows calling the API. If you manage multiple tenants under an MSP account, see [MSP API access](/api/guides/msp-api-access) for how to scope calls to a specific tenant. Here's how to add the token to the request header using cURL:
For the cloud solution we are limiting the usage to 120 requests per minute with burst of 1200 requests. If your workload requires more requests, please contact us at [support@netbird.io](mailto:support@netbird.io).
diff --git a/src/pages/ipa/guides/msp-api-access.mdx b/src/pages/ipa/guides/msp-api-access.mdx
new file mode 100644
index 00000000..6a1b1092
--- /dev/null
+++ b/src/pages/ipa/guides/msp-api-access.mdx
@@ -0,0 +1,76 @@
+import {Note} from "../../../components/mdx";
+export const description =
+ 'Use the account query parameter to scope NetBird API calls to a specific tenant under your MSP account, so a single PAT can drive automation across every tenant you manage.'
+
+# MSP API access
+
+If you manage multiple tenants under an MSP account, the NetBird API accepts an `account` query parameter that scopes a request to a specific tenant. A single personal access token (PAT) can drive automation across every tenant under your MSP account — no token swapping, no separate logins. {{ className: 'lead' }}
+
+## Who this is for
+
+MSP and MSSP account holders managing multiple customer tenants from a single NetBird account. The `account` query parameter is meaningful only inside an MSP account; it has no effect on a standalone account.
+
+If you are not yet an MSP, see the [MSP Portal guide](/manage/for-partners/msp-portal) for how to apply.
+
+## Setting up an automation user
+
+Before you can make cross-tenant API calls you need a PAT issued to a real user inside your MSP account.
+
+1. **Pick a user** inside your MSP account. Any real user with access to the tenants you want to automate will work, including an existing admin. Consider creating a dedicated automation user if you want clean audit attribution, an independent PAT rotation cadence, or independence from any individual employee's account lifecycle. Service users are not supported for cross-tenant calls — they remain fine for single-tenant API automation.
+2. **Add the user to a permission group** that has access to every tenant you want to automate.
+3. **Generate a PAT** for that user from the dashboard. Go to **Team** → **Users**, open the user, then **Access Tokens** → **Create Access Token**. Save the token securely — it is only shown once.
+
+
+ The `account` query parameter requires a PAT issued to a real user (one with an email-bound identity). It is not honored on PATs issued to service users — those PATs continue to work for API calls scoped to a single tenant.
+
+
+## How it works
+
+Append `?account=` to any cross-tenant-capable endpoint to execute the request inside that tenant. Omit the parameter to operate on the MSP account itself.
+
+### Finding a tenant ID
+
+List the tenants under your MSP account to retrieve their IDs. Use the same PAT (no `account` parameter — this call targets the MSP):
+
+```bash {{ title: 'List tenants under your MSP account' }}
+curl https://api.netbird.io/api/integrations/msp/tenants \
+ -H "Authorization: Token {token}"
+```
+
+Each tenant object in the response includes an `id` field — that is the value to pass as `?account=`. See the [MSP API reference](/api/resources/msp) for the full schema.
+
+### Calling endpoints in a tenant
+
+```bash {{ title: 'List setup keys inside a tenant' }}
+curl https://api.netbird.io/api/setup-keys?account= \
+ -H "Authorization: Token {token}"
+```
+
+The same pattern works for writes:
+
+```bash {{ title: 'Create a setup key inside a tenant' }}
+curl -X POST https://api.netbird.io/api/setup-keys?account= \
+ -H "Authorization: Token {token}" \
+ -H "Content-Type: application/json" \
+ -d '{"name":"bootstrap","type":"reusable"}'
+```
+
+## Common automation flow
+
+A typical MSP onboarding script looks like this:
+
+- Create the tenant via the MSP API (no `account` parameter — this targets the MSP itself).
+- Bootstrap a setup key inside the new tenant: `POST /api/setup-keys?account=`.
+- Create networks, groups, policies, and users inside the tenant: `POST /api/networks?account=`, `POST /api/users?account=`, and so on.
+
+The same PAT is used for every step. Only the `account` parameter changes.
+
+## Auditing and security
+
+- Activity from cross-tenant calls appears in each target tenant's audit log labeled **External**, the same way an MSP user's UI actions do.
+- A PAT with write access across every tenant under your MSP has a wide blast radius. Treat it accordingly — MFA on the underlying SSO identity, regular PAT rotation, and a secrets manager on the caller side.
+- Cross-tenant calls share the same rate limit as any other PAT (120 requests per minute, 1200 burst on NetBird Cloud). The budget is per PAT, not per tenant.
+
+
+
+
diff --git a/src/pages/manage/for-partners/msp-portal.mdx b/src/pages/manage/for-partners/msp-portal.mdx
index 99b0c2dd..953132c9 100644
--- a/src/pages/manage/for-partners/msp-portal.mdx
+++ b/src/pages/manage/for-partners/msp-portal.mdx
@@ -19,6 +19,10 @@ or inconvenient customer-specific URLs.
+
+ Prefer to automate tenant operations? You can drive setup keys, networks, users and more across every tenant under your MSP account via the API — see [MSP API access](/api/guides/msp-api-access).
+
+
## How to Apply for an MSP Account?
To apply for an MSP account, follow these steps:
diff --git a/src/pages/manage/public-api/index.mdx b/src/pages/manage/public-api/index.mdx
index 7a75eafa..7f43f581 100644
--- a/src/pages/manage/public-api/index.mdx
+++ b/src/pages/manage/public-api/index.mdx
@@ -61,6 +61,10 @@ Be aware that once you close the popup it is impossible to see the plain version
It's important to keep your personal access tokens secure, as they can provide access to sensitive data and actions within your account. You should treat your personal access tokens like you would treat your password and never share them with anyone else.
+
+ **Using PATs across tenants under an MSP account.** A PAT issued to a real user inside an MSP account can act as a single key for automation across every tenant the user has access to — append `?account=` to any API call to scope it to a specific tenant. Treat such a token accordingly: MFA on the underlying SSO identity, regular rotation, and a secrets manager on the caller side. See [MSP API access](/api/guides/msp-api-access) for the full setup.
+
+
### Using access tokens
Once you have created an access token, you can use it to authenticate API requests to NetBird. See [NetBird API](/api/introduction) documentation for detailed usage.
+