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.