Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
Explain organisation access refusals in webhook setup
pulse-triage[bot]5d43f4055ebe
diff --git a/docs/WEBHOOKS.md b/docs/WEBHOOKS.mdindex a35faaa155..5f169dc680 100644--- a/docs/WEBHOOKS.md+++ b/docs/WEBHOOKS.md@@ -425,14 +425,40 @@ In shared-process multi-tenant mode (self-hosted with `PULSE_MULTI_TENANT_ENABLEUse this for one owner separating internal sites, departments, teams, or environments. It is not the canonical Pulse MSP model for separate customer businesses; MSP uses isolated client workspaces with their own runtime boundaries.-The organization for a request is resolved in this order:--1. `X-Pulse-Org-ID: <orgID>` header (the way API clients or internal middleware should target a specific organization).-2. `pulse_org_id` session cookie (browser sessions).-3. An org-bound API token (a token scoped to a single org needs no header).-4. Fallback: the `default` org.--Suspended or pending-deletion organizations return `403`, and an unknown org ID returns `400`.+### Select the organisation without widening access++**Selection is not authorisation.** Pulse selects a request's organisation in+this order, then checks whether the authenticated user or token may access it:++1. An explicit `X-Pulse-Org-ID` header.+2. Otherwise, the `pulse_org_id` browser cookie.+3. With neither present, a token bound to exactly one organisation selects it.+4. Otherwise, the `default` organisation; this is not permission to access it.++A header or cookie takes precedence over automatic token selection, but does+not change the token's binding. A token supplied alongside a signed-in browser+session is checked as that token: the user's administrator access does not+widen it. A token bound to several organisations needs an explicit selection+when targeting a non-default organisation; Pulse does not guess which one.++For the UI, use the **Org Switcher** and confirm the ID in **Settings →+Organization → Overview**, not just a similar display name. For automation,+use a token bound to the intended organisation with only the required scopes.+Keep authentication in a [private header file](API.md#api-token-recommended);+do not copy browser cookies, CSRF tokens or credentials into commands. If you+supply `X-Pulse-Org-ID`, it must name an organisation the token already allows.++| Existing response | What to check before another change |+|---|---|+| `400 invalid_org` | Confirm the Pulse instance and exact organisation ID. An ID from another installation is not a destination on this one. |+| `403 access_denied` | Check the selected header/cookie and the token's organisation binding, or the signed-in user's membership. Adding scopes does not grant access to another organisation. |+| `403 org_suspended` | The organisation is suspended or pending deletion. Stop the integration change; renaming, recreating or re-enrolling it is not access recovery. |++Read the error code and message locally: HTTP `403` alone does not distinguish+organisation access from a missing scope or another gate. Do not replace a+scoped token with an unrestricted one to clear the error. Keep complete+webhook responses and configuration private; share only a locally reviewed,+redacted error and consistent aliases if help is needed.### Wiring organization alerts into external systems@@ -448,7 +474,12 @@ conditions above](#-delivery-contract) and its [resolution reason](#resolved-doeDo not label a moved close as recovery. Add authentication as a custom headerin the settings form; keep its value private.-Configure it from the UI (**Alerts → Notifications → Add Webhook**) per org, or programmatically with an org-bound admin token:+Configure it from the UI (**Alerts → Notifications → Add Webhook**) in the+intended organisation. The HTTP example below describes the API contract;+its authentication values are placeholders, not a command to paste into a+terminal. Programmatic creation needs an organisation-bound token with+`settings:write` and the matching selection above. Keep the receiver's own+credential private too; it is not a Pulse API token.```httpPOST /api/notifications/webhooksdiff --git a/frontend-modern/public/docs/WEBHOOKS.md b/frontend-modern/public/docs/WEBHOOKS.mdindex a35faaa155..5f169dc680 100644--- a/frontend-modern/public/docs/WEBHOOKS.md+++ b/frontend-modern/public/docs/WEBHOOKS.md@@ -425,14 +425,40 @@ In shared-process multi-tenant mode (self-hosted with `PULSE_MULTI_TENANT_ENABLEUse this for one owner separating internal sites, departments, teams, or environments. It is not the canonical Pulse MSP model for separate customer businesses; MSP uses isolated client workspaces with their own runtime boundaries.-The organization for a request is resolved in this order:--1. `X-Pulse-Org-ID: <orgID>` header (the way API clients or internal middleware should target a specific organization).-2. `pulse_org_id` session cookie (browser sessions).-3. An org-bound API token (a token scoped to a single org needs no header).-4. Fallback: the `default` org.--Suspended or pending-deletion organizations return `403`, and an unknown org ID returns `400`.+### Select the organisation without widening access++**Selection is not authorisation.** Pulse selects a request's organisation in+this order, then checks whether the authenticated user or token may access it:++1. An explicit `X-Pulse-Org-ID` header.+2. Otherwise, the `pulse_org_id` browser cookie.+3. With neither present, a token bound to exactly one organisation selects it.+4. Otherwise, the `default` organisation; this is not permission to access it.++A header or cookie takes precedence over automatic token selection, but does+not change the token's binding. A token supplied alongside a signed-in browser+session is checked as that token: the user's administrator access does not+widen it. A token bound to several organisations needs an explicit selection+when targeting a non-default organisation; Pulse does not guess which one.++For the UI, use the **Org Switcher** and confirm the ID in **Settings →+Organization → Overview**, not just a similar display name. For automation,+use a token bound to the intended organisation with only the required scopes.+Keep authentication in a [private header file](API.md#api-token-recommended);+do not copy browser cookies, CSRF tokens or credentials into commands. If you+supply `X-Pulse-Org-ID`, it must name an organisation the token already allows.++| Existing response | What to check before another change |+|---|---|+| `400 invalid_org` | Confirm the Pulse instance and exact organisation ID. An ID from another installation is not a destination on this one. |+| `403 access_denied` | Check the selected header/cookie and the token's organisation binding, or the signed-in user's membership. Adding scopes does not grant access to another organisation. |+| `403 org_suspended` | The organisation is suspended or pending deletion. Stop the integration change; renaming, recreating or re-enrolling it is not access recovery. |++Read the error code and message locally: HTTP `403` alone does not distinguish+organisation access from a missing scope or another gate. Do not replace a+scoped token with an unrestricted one to clear the error. Keep complete+webhook responses and configuration private; share only a locally reviewed,+redacted error and consistent aliases if help is needed.### Wiring organization alerts into external systems@@ -448,7 +474,12 @@ conditions above](#-delivery-contract) and its [resolution reason](#resolved-doeDo not label a moved close as recovery. Add authentication as a custom headerin the settings form; keep its value private.-Configure it from the UI (**Alerts → Notifications → Add Webhook**) per org, or programmatically with an org-bound admin token:+Configure it from the UI (**Alerts → Notifications → Add Webhook**) in the+intended organisation. The HTTP example below describes the API contract;+its authentication values are placeholders, not a command to paste into a+terminal. Programmatic creation needs an organisation-bound token with+`settings:write` and the matching selection above. Keep the receiver's own+credential private too; it is not a Pulse API token.```httpPOST /api/notifications/webhooksdiff --git a/frontend-modern/src/features/docs/__tests__/webhookExampleGuide.test.ts b/frontend-modern/src/features/docs/__tests__/webhookExampleGuide.test.tsindex 453145f297..14d1a5471a 100644--- a/frontend-modern/src/features/docs/__tests__/webhookExampleGuide.test.ts+++ b/frontend-modern/src/features/docs/__tests__/webhookExampleGuide.test.ts@@ -28,6 +28,32 @@ describe('copyable webhook example', () => {);});+ it('keeps organisation selection, access refusals and private authentication beside the API example', () => {+ const article = render();+ const section = article.querySelector('#select-the-organisation-without-widening-access');+ expect(section).not.toBeNull();+ const text = article.textContent?.replace(/\s+/g, ' ');+ expect(text).toContain('Selection is not authorisation.');+ expect(text).toContain("the user's administrator access does not widen it");+ expect(text).toContain('Adding scopes does not grant access to another organisation');+ const rows = [...article.querySelectorAll('tr')].map((row) => row.textContent);+ for (const code of ['400 invalid_org', '403 access_denied', '403 org_suspended']) {+ expect(rows.some((row) => row?.includes(code))).toBe(true);+ }+ expect(article.querySelector('a[href="/docs/API#api-token-recommended"]')?.textContent).toBe(+ 'private header file',+ );+ const example = [...article.querySelectorAll('pre code')].find((block) =>+ block.textContent?.startsWith('POST /api/notifications/webhooks\n'),+ )?.textContent;+ expect(example).toContain('X-Pulse-Org-ID: acme-corp');+ expect(example).toContain('Authorization: Bearer <token with settings:write>');+ const config = JSON.parse(example!.split('\n\n')[1]);+ expect(config.url).toBe('https://psa.example.com/inbound/pulse');+ expect(config.headers.Authorization).toBe('Bearer <psa-token>');+ expect(example).not.toMatch(/Cookie:|pulse_session|--insecure/);+ });+it('explains the simple-test blind spot and links the existing structured group example', () => {const article = render();const text = article.textContent?.replace(/\s+/g, ' ');