From 54f30c6c91c2eb2e0e806546edd5d7ca1a6af78a Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Tue, 17 Mar 2026 10:55:51 +0100 Subject: [PATCH] docs: simplify visibilityPermission docs to match type constraints Since visibilityPermission is typed as BasicPermission and authorize() returns DefinitivePolicyDecision (ALLOW/DENY only), remove misleading references to CONDITIONAL decisions which can never occur. Signed-off-by: Patrik Oldsberg Made-with: Cursor --- docs/backend-system/core-services/actions-registry.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/docs/backend-system/core-services/actions-registry.md b/docs/backend-system/core-services/actions-registry.md index b2ebcc1d04..e8e2dc7bb2 100644 --- a/docs/backend-system/core-services/actions-registry.md +++ b/docs/backend-system/core-services/actions-registry.md @@ -160,14 +160,9 @@ export const myPlugin = createBackendPlugin({ ## Permissions -Actions can optionally declare a `visibilityPermission` to control visibility and access through the Backstage permissions framework. This permission is evaluated without any resource context and is intended for unconditional (non-resource) permissions only. When such a permission is set, the action is only visible in listings and accessible by users who are authorized. +Actions can optionally declare a `visibilityPermission` to control visibility and access through the Backstage permissions framework. The `visibilityPermission` must be a `BasicPermission` (not a resource permission). When set, the action is only visible in listings and accessible by callers who are authorized. -When accessed via the Actions Service or the `/.backstage/actions/v1/...` HTTP endpoints, actions that are not authorized by the permission policy are filtered from list results and return a `404 Not Found` on invocation, as if they don't exist. In particular: - -- `ALLOW` decisions make the action visible and invokable. -- `DENY` and `CONDITIONAL` decisions are both treated as not authorized, so the action is hidden from listings and returns `404 Not Found` when invoked. - -Because `visibilityPermission` is evaluated without resource context, resource-based or otherwise conditional permissions (that may normally return `CONDITIONAL` decisions) are not supported here and will effectively behave as denied. +When accessed via the Actions Service or the `/.backstage/actions/v1/...` HTTP endpoints, actions that are denied by the permission policy are filtered from list results and return a `404 Not Found` on invocation, as if they don't exist. Permissions declared on actions are automatically registered with the `PermissionsRegistryService` so they appear in the permission policy system.