Update RBAC docs for non-root admin role management (#965)

* docs: update RBAC docs for non-root admin role management

* docs: add changelog entry

Author: Roma36

docs/concepts/authorization/assigning-roles-api-keys.md

@@ -13,10 +13,14 @@
 
 ### Assign roles to API keys directly using the web UI
 
+!!! info "Permission Scope"
+    - **Root Space Admins** can create/modify/delete API keys and manage role bindings across all spaces
+    - **Non-root Space Admins** can view all API keys but only manage role bindings for spaces they administer; they cannot create/modify/delete API keys
+
 1. Verify you meet the prerequisites:
     1. The selected management strategy for your organization must be User Management.
     2. The key must exist in your Spacelift organization.
-    3. You must have appropriate permissions to manage API key roles.
+    3. You must have Space Admin permissions on the target space where you want to assign roles (or Root Space Admin permissions for all spaces).
     4. Spaces where you want to assign roles must exist.
 2. Navigate to _API Key Management_:
     1. Click your name in the bottom left corner of the Spacelift interface.

docs/concepts/authorization/assigning-roles-groups.md

@@ -6,10 +6,14 @@ IdP groups can receive roles through direct group assignment. Assign roles to th
 
 ### Assign roles to IdP groups using the web UI
 
+!!! info "Permission Scope"
+    - **Root Space Admins** can create/modify/delete IdP group mappings and manage role bindings across all spaces
+    - **Non-root Space Admins** can view all IdP group mappings but only manage role bindings for spaces they administer; they cannot create/modify/delete IdP group mappings
+
 1. Verify you meet the prerequisites:
     1. The selected management strategy for your organization must be User Management.
     2. Your identity provider [must be connected to Spacelift](../../integrations/single-sign-on/README.md).
-    3. You must have appropriate permissions to manage user group roles.
+    3. You must have Space Admin permissions on the target space where you want to assign roles (or Root Space Admin permissions for all spaces).
     4. Target spaces must exist where you want to assign roles.
 2. Navigate to IdP group mapping:
     1. Click your name in the bottom left corner of the Spacelift interface.

docs/concepts/authorization/assigning-roles-users.md

@@ -13,9 +13,13 @@ Users can get permissions from three sources:
 
 ### Assign roles to users directly using the web UI
 
+!!! info "Permission Scope"
+    - **Root Space Admins** can manage role bindings across all spaces and invite/revoke users
+    - **Non-root Space Admins** can only manage role bindings for spaces they administer and cannot invite/revoke users
+
 1. Verify you meet the prerequisites:
       - User must be invited to the Spacelift organization.
-      - You must have appropriate permissions to manage user roles.
+      - You must have Space Admin permissions on the target space where you want to assign roles (or Root Space Admin permissions for all spaces).
       - Target spaces must exist where you want to assign roles.
       - The selected management strategy for your organization must be User Management.
 2. Navigate to _User Management_:

docs/concepts/authorization/rbac-system.md

@@ -259,10 +259,25 @@ System roles are immutable and cannot be modified or deleted, ensuring consisten
 - Create and modify stacks.
 - Create and modify contexts and policies.
 - Manage space settings (when assigned to specific space).
+- View all roles, users, API keys, and IdP group mappings in the organization (read-only).
+- Manage role bindings (assign/remove roles) for users, API keys, and IdP groups within the spaces they administer.
 - Equivalent to legacy **Admin** role.
 
-!!! info "Root Space Admin"
-    Users with Space Admin role on the **root** space become **Root Space Admins** with account-wide privileges including SSO setup, VCS configuration, and audit trail management.
+!!! info "Root Space Admin vs Non-root Space Admin"
+    **Root Space Admins** (Space Admin role on the **root** space) have account-wide privileges including:
+
+    - All Space Admin permissions across all spaces
+    - SSO setup, VCS configuration, audit trail management
+    - Invite/revoke users and create/modify/delete roles
+    - Create/modify/delete API keys and IdP group mappings
+    - Manage role bindings across all spaces
+
+    **Non-root Space Admins** (Space Admin role on any non-root space) have limited privileges:
+
+    - Space Admin permissions only within the spaces they administer
+    - Can view all roles, users, API keys, and IdP group mappings
+    - Can manage role bindings only for the spaces they administer
+    - Cannot invite/revoke users, create/modify/delete roles, or create/modify/delete API keys and IdP group mappings
 
 #### Worker pool controller
 

docs/concepts/spaces/access-control.md

@@ -35,12 +35,17 @@ A "Root Space Admin" is a user given administrative permissions to the `root` sp
 
 | Action / Role                                    | Root Space Admin | Space Admin | Space Writer | Space Reader |
 | ------------------------------------------------ | ---------------- | ----------- | ------------ | ------------ |
-| Set up SSO                                       | ✅                | ❌           | ❌            | ❌            |
-| Set up VCS                                       | ✅                | ❌           | ❌            | ❌            |
-| Manage Sessions                                  | ✅                | ❌           | ❌            | ❌            |
-| Manage Login Policies & User Management Controls | ✅                | ❌           | ❌            | ❌            |
-| Manage Audit Trails                              | ✅                | ❌           | ❌            | ❌            |
-| Manage Spaces                                    | ✅                | ✅*          | ❌            | ❌            |
+| Set up SSO                                        | ✅                | ❌           | ❌            | ❌            |
+| Set up VCS                                        | ✅                | ❌           | ❌            | ❌            |
+| Manage Sessions                                   | ✅                | ❌           | ❌            | ❌            |
+| Manage Login Policies & User Management Controls  | ✅                | ❌           | ❌            | ❌            |
+| Manage Audit Trails                               | ✅                | ❌           | ❌            | ❌            |
+| Invite/Revoke Users                               | ✅                | ❌           | ❌            | ❌            |
+| Create/Modify/Delete Roles                        | ✅                | ❌           | ❌            | ❌            |
+| Create/Modify/Delete API Keys, IdP Group Mappings | ✅                | ❌           | ❌            | ❌            |
+| View Roles, Users, API Keys, IdP Group Mappings  | ✅                | ✅           | ❌            | ❌            |
+| Manage Role Bindings                             | ✅                | ✅*          | ❌            | ❌            |
+| Manage Spaces                                    | ✅                | ✅**         | ❌            | ❌            |
 | Manage Stack Config Settings                     | ✅                | ✅           | ❌            | ❌            |
 | Manage Worker Pools, Contexts                    | ✅                | ✅           | ❌            | ❌            |
 | Manage Stack Env Vars                            | ✅                | ✅           | ✅            | ❌            |
@@ -49,7 +54,9 @@ A "Root Space Admin" is a user given administrative permissions to the `root` sp
 | View Spaces                                      | ✅                | ✅           | ✅            | ✅            |
 | View Worker Pools, Contexts                      | ✅                | ✅           | ✅            | ✅            |
 
-*Can only manage assigned space(s)
+*Can only manage role bindings for assigned space(s)
+
+**Can only manage assigned space(s)
 
 ## Authorization methods
 

docs/product/changelog.md

@@ -4,6 +4,12 @@ description: Find out about the latest changes to Spacelift.
 
 # Changelog
 
+## 2025-11-17
+
+### Features
+
+- **Authorization & RBAC**: Non-root Space Admins can now view all roles, users, API keys, and IdP group mappings (read-only) and manage role bindings within their administered spaces. Previously, these capabilities were limited to Root Space Admins only. See the [RBAC system documentation](../concepts/authorization/rbac-system.md#space-admin) for details.
+
 ## 2025-11-13
 
 ### Features