From 2c98baabeac49673c9ed0ad2e9ef91fb8795beb8 Mon Sep 17 00:00:00 2001 From: "pulse-triage[bot]" <249995291+pulse-triage[bot]@users.noreply.github.com> Date: Thu, 1 Oct 2026 08:44:10 +0100 Subject: [PATCH] Align administration guide details with current handlers Use the accepted organisation ID alphabet and canonical resource types, and expect the documented role assignments to return 204. Keep the guide lifecycle checks at the existing API contract. Contract-Neutral: Documentation and test expectations only; API methods, validation, authentication and tenant isolation are unchanged. Change-source: pulse-maintainer --- docs/API.md | 4 ++-- docs/MULTI_TENANT.md | 16 +++++++++------- frontend-modern/public/docs/API.md | 4 ++-- frontend-modern/public/docs/MULTI_TENANT.md | 16 +++++++++------- internal/api/admin_docs_test.go | 4 ++-- 5 files changed, 24 insertions(+), 20 deletions(-) diff --git a/docs/API.md b/docs/API.md index 285d945cc..dde843211 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1178,7 +1178,7 @@ Returns organizations accessible to the authenticated user. ```json { "id": "acme-corp", "displayName": "Acme Corporation" } ``` -The creator becomes the owner and first member. Organization IDs must be lowercase alphanumeric with hyphens, 3-64 characters. +The creator becomes the owner and first member. Organization IDs use letters, digits, periods, underscores or hyphens, 1–64 characters, but cannot be `.` or `..`. Prefer a simple lowercase/hyphen ID such as the example. ### Get Organization `GET /api/orgs/{id}` (requires `settings:read`) @@ -1229,7 +1229,7 @@ Returns resources shared inbound to this organization from other organizations. "accessRole": "viewer" } ``` -Share a resource with another organization. Valid resource types: `vm`, `container`, `agent`, `storage`, `pbs`, `pmg` (not `host`). Access roles: `viewer`, `editor`, `admin`. Admin or owner role required on the source org. The share is pending until a target-org admin or owner accepts it in Pulse; changing its access role requires acceptance again. +Share a resource with another organization, using the resource type and ID returned by Pulse. Supported types include `vm`, `system-container`, `agent`, `node`, `docker-host`, `storage`, `pbs` and `pmg`; generic `host` and `container` types are not supported. Access roles: `viewer`, `editor`, `admin`. Admin or owner role required on the source org. The share is pending until a target-org admin or owner accepts it in Pulse; changing its access role requires acceptance again. ### Delete Share `DELETE /api/orgs/{id}/shares/{shareId}` (requires `settings:write`, session auth only) diff --git a/docs/MULTI_TENANT.md b/docs/MULTI_TENANT.md index 88276d41f..4e7e4d070 100644 --- a/docs/MULTI_TENANT.md +++ b/docs/MULTI_TENANT.md @@ -87,9 +87,10 @@ the relevant redacted error, not whole member or infrastructure responses. {"id": "production-datacenter", "displayName": "Production Datacenter"} ``` -The creator becomes the owner. `id` is a lowercase alphanumeric/hyphen ID -(3–64 characters); `displayName` is the name shown in Pulse. `name` and -`description` are not the creation fields. +The creator becomes the owner. `id` is a stable ID of 1–64 characters using +letters, digits, periods, underscores or hyphens, but not `.` or `..`; use a +simple lowercase/hyphen ID such as the example. `displayName` is the name +shown in Pulse. `name` and `description` are not the creation fields. ### Switching Organizations @@ -145,10 +146,11 @@ Until acceptance, the share is pending and does not grant access. } ``` -Use `accessRole`, not `role`. Supported resource types are `vm`, `container`, -`agent`, `storage`, `pbs` and `pmg`; `host` is not supported. Use the resource ID -returned by Pulse, not a display name. Changing a share's access role makes it -pending again, so the target must accept the new grant. +Use `accessRole`, not `role`, and the resource type and ID returned by Pulse, +not a display name. Supported types include `vm`, `system-container`, `agent`, +`node`, `docker-host`, `storage`, `pbs` and `pmg`; the generic types `host` and +`container` are not supported. Changing a share's access role makes it pending +again, so the target must accept the new grant. **Read-only incoming shares:** ```bash diff --git a/frontend-modern/public/docs/API.md b/frontend-modern/public/docs/API.md index 285d945cc..dde843211 100644 --- a/frontend-modern/public/docs/API.md +++ b/frontend-modern/public/docs/API.md @@ -1178,7 +1178,7 @@ Returns organizations accessible to the authenticated user. ```json { "id": "acme-corp", "displayName": "Acme Corporation" } ``` -The creator becomes the owner and first member. Organization IDs must be lowercase alphanumeric with hyphens, 3-64 characters. +The creator becomes the owner and first member. Organization IDs use letters, digits, periods, underscores or hyphens, 1–64 characters, but cannot be `.` or `..`. Prefer a simple lowercase/hyphen ID such as the example. ### Get Organization `GET /api/orgs/{id}` (requires `settings:read`) @@ -1229,7 +1229,7 @@ Returns resources shared inbound to this organization from other organizations. "accessRole": "viewer" } ``` -Share a resource with another organization. Valid resource types: `vm`, `container`, `agent`, `storage`, `pbs`, `pmg` (not `host`). Access roles: `viewer`, `editor`, `admin`. Admin or owner role required on the source org. The share is pending until a target-org admin or owner accepts it in Pulse; changing its access role requires acceptance again. +Share a resource with another organization, using the resource type and ID returned by Pulse. Supported types include `vm`, `system-container`, `agent`, `node`, `docker-host`, `storage`, `pbs` and `pmg`; generic `host` and `container` types are not supported. Access roles: `viewer`, `editor`, `admin`. Admin or owner role required on the source org. The share is pending until a target-org admin or owner accepts it in Pulse; changing its access role requires acceptance again. ### Delete Share `DELETE /api/orgs/{id}/shares/{shareId}` (requires `settings:write`, session auth only) diff --git a/frontend-modern/public/docs/MULTI_TENANT.md b/frontend-modern/public/docs/MULTI_TENANT.md index 88276d41f..4e7e4d070 100644 --- a/frontend-modern/public/docs/MULTI_TENANT.md +++ b/frontend-modern/public/docs/MULTI_TENANT.md @@ -87,9 +87,10 @@ the relevant redacted error, not whole member or infrastructure responses. {"id": "production-datacenter", "displayName": "Production Datacenter"} ``` -The creator becomes the owner. `id` is a lowercase alphanumeric/hyphen ID -(3–64 characters); `displayName` is the name shown in Pulse. `name` and -`description` are not the creation fields. +The creator becomes the owner. `id` is a stable ID of 1–64 characters using +letters, digits, periods, underscores or hyphens, but not `.` or `..`; use a +simple lowercase/hyphen ID such as the example. `displayName` is the name +shown in Pulse. `name` and `description` are not the creation fields. ### Switching Organizations @@ -145,10 +146,11 @@ Until acceptance, the share is pending and does not grant access. } ``` -Use `accessRole`, not `role`. Supported resource types are `vm`, `container`, -`agent`, `storage`, `pbs` and `pmg`; `host` is not supported. Use the resource ID -returned by Pulse, not a display name. Changing a share's access role makes it -pending again, so the target must accept the new grant. +Use `accessRole`, not `role`, and the resource type and ID returned by Pulse, +not a display name. Supported types include `vm`, `system-container`, `agent`, +`node`, `docker-host`, `storage`, `pbs` and `pmg`; the generic types `host` and +`container` are not supported. Changing a share's access role makes it pending +again, so the target must accept the new grant. **Read-only incoming shares:** ```bash diff --git a/internal/api/admin_docs_test.go b/internal/api/admin_docs_test.go index 15e2ed1a0..e625e449d 100644 --- a/internal/api/admin_docs_test.go +++ b/internal/api/admin_docs_test.go @@ -77,8 +77,8 @@ func TestAdminDocsCustomRoleLifecycle(t *testing.T) { }{ {http.MethodPost, "/api/admin/roles", adminDocBodies(t, "RBAC", "Creating a Role")[0], h.HandleRoles, http.StatusOK}, {http.MethodPut, "/api/admin/roles/alert-manager", adminDocBodies(t, "RBAC", "Updating a Role")[0], h.HandleRoles, http.StatusOK}, - {http.MethodPut, "/api/admin/users/jane/roles", assignments[0], h.HandleUserRoleActions, http.StatusOK}, - {http.MethodPut, "/api/admin/users/jane/roles", assignments[1], h.HandleUserRoleActions, http.StatusOK}, + {http.MethodPut, "/api/admin/users/jane/roles", assignments[0], h.HandleUserRoleActions, http.StatusNoContent}, + {http.MethodPut, "/api/admin/users/jane/roles", assignments[1], h.HandleUserRoleActions, http.StatusNoContent}, {http.MethodDelete, "/api/admin/users/jane", nil, h.HandleUserRoleActions, http.StatusNoContent}, {http.MethodDelete, "/api/admin/roles/alert-manager", nil, h.HandleRoles, http.StatusNoContent}, }