diff --git a/docs/concepts/authorization/README.md b/docs/concepts/authorization/README.md
new file mode 100644
index 000000000..0f17ac7d2
--- /dev/null
+++ b/docs/concepts/authorization/README.md
@@ -0,0 +1,115 @@
+# Authorization & RBAC
+
+Spacelift provides a comprehensive **Role-Based Access Control (RBAC)** system designed for enterprise infrastructure
+teams. RBAC enables fine-grained, customizable permissions giving
+you precise control over who can access what resources and perform which actions.
+
+## Evolution from Legacy System Roles
+
+Spacelift has evolved from simple **legacy system roles** (Read, Write, Admin) to a custom RBAC system that
+offers:
+
+- **Custom Roles**: Create roles tailored to your organization's specific needs
+- **Granular Actions**: Composable permissions like `run:trigger`, `stack:manage`
+- **Flexible Assignment**: Assign roles to users, IdP groups, and API keys
+- **Space-Based Control**: All roles are bound to specific [Spaces](../spaces/README.md) for organized access management
+
+## Core RBAC Architecture
+
+RBAC operates on three fundamental concepts: actions, actors, and subjects.
+
+### Actions
+
+**Actions** are the smallest unit of permission granularity. They define specific operations that can be performed
+within Spacelift. Examples include:
+
+- `run:trigger`: Trigger stack runs
+- `stack:manage`: Create and modify stacks
+
+### Actors
+
+**Actors** are entities that perform actions in the system:
+
+- **Users**: Individual team members authenticated through your identity provider
+- **API Keys**: Programmatic access tokens for automation
+- **IdP Groups**: Groups of users as defined by your identity provider
+
+### Subjects
+
+**Subjects** are the resources being acted upon. Examples include:
+
+- **Stacks**: Infrastructure definitions and their runs
+- **Contexts**: Collections of environment variables and files
+- **Policies**: Rules that govern various Spacelift behaviors
+- **Spaces**: Organizational containers for resources
+
+## Getting Started with RBAC
+
+### For new Spacelift users
+
+If you're new to Spacelift, you can start using RBAC right away. Follow these steps to set up your RBAC configuration:
+
+1. Navigate to **Organization Settings** → **Access Control Center** → **Roles**
+2. Review the predefined roles (Space Admin, Space Writer, Space Reader). These are equivalent to legacy roles.
+3. (Optional) Create custom roles with specific actions for your use cases
+4. Assign roles to users and spaces
+
+### Existing Users: Migration from Legacy System Roles
+
+If you're currently using legacy system roles (Read/Write/Admin), your existing configurations have been automatically
+migrated to equivalent RBAC roles:
+
+- **Reader** → **Space Reader**
+- **Writer** → **Space Writer**
+- **Admin** → **Space Admin**
+
+## Authorization Strategies
+
+Spacelift offers two primary approaches for managing user access:
+
+### User Management (Recommended for Most Organizations)
+
+- **GUI or API based**: Manage access using the Spacelift web interface or using the terraform provider
+- **User-friendly**: Invite users and assign roles without writing policies
+- **IdP Integration**: Seamlessly integrate with your identity provider for user management
+
+### Login Policies (Advanced)
+
+- **Policy-as-code**: Define authorization rules using [Open Policy Agent](https://www.openpolicyagent.org/) (OPA)
+- **Dynamic**: Conditional role assignment based on user attributes
+- **Flexible**: Support for complex authorization logic
+
+## Key RBAC Features
+
+### Access Control Center
+
+A dedicated section in Organization Settings for managing your RBAC configuration:
+
+- Create and manage custom roles
+- Assign roles to users, groups, and API keys
+- Monitor role assignments across spaces
+
+### Custom Roles
+
+Go beyond predefined roles by creating custom roles that match your organization's specific needs.
+
+### Space-Bound Permissions
+
+All roles are assigned to specific spaces, providing:
+
+- **Isolation**: Permissions are contained within designated spaces
+- **Inheritance**: Leverage space hierarchies for permission flow
+- **Scalability**: Manage permissions at the appropriate organizational level
+
+## Next Steps
+
+Dive deeper into RBAC with these guides:
+
+- **[RBAC System](rbac-system.md)** - Detailed explanation of Spacelift's RBAC implementation
+
+## Related Topics
+
+- **[User Management](../user-management/README.md)**: Invite and manage team members
+- **[Spaces](../spaces/README.md)**: Organize resources with spaces
+- **[Login Policies](../policy/login-policy.md)**: Policy-based access control
+- **[Single Sign-On](../../integrations/single-sign-on/README.md)**: Enterprise identity integration
diff --git a/docs/concepts/authorization/assigning-roles-api-keys.md b/docs/concepts/authorization/assigning-roles-api-keys.md
new file mode 100644
index 000000000..217678994
--- /dev/null
+++ b/docs/concepts/authorization/assigning-roles-api-keys.md
@@ -0,0 +1,317 @@
+# API key role bindings
+
+[API](./../../integrations/api.md#spacelift-api-key-token) keys can receive roles through three methods:
+
+- **Direct Assignment**: Assign roles directly to the API key
+- **IdP Group Assignment**: Associate API keys with IdP groups to inherit group-based role assignment
+- **Login Policy Assignment**: Use OPA policies to assign roles based on API key attributes (this can include assignment based on IdP group membership)
+
+!!! note "Immediate Role Changes"
+    Except for Login Policies, role assignments and changes to roles take effect immediately (they force re-authentication if needed).
+
+## Assigning roles
+
+### Assigning roles to API keys directly using the web UI
+
+1. 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
+    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
+    2. Go to **Organization Settings**
+    3. Go to ** **API Keys** in the **Identity Management** section
+    4. Find the API key you want to assign roles to
+    5. Click on the API key row to open its details
+3. Access Role Management
+    1. In the API key details page, click **Manage Roles**
+    2. This opens the role assignment interface for the API key
+4. Assign Roles
+    1. **Select Role**: Choose appropriate role for the automation
+    2. **Select Space**: Choose the space where the role applies
+    3. **Save Assignment**: Confirm the role assignment
+
+### Assigning roles to API keys directly using the terraform provider
+
+Refer to [Spacelift Terraform provider documentation](https://registry.terraform.io/providers/spacelift-io/spacelift/latest/docs) for more details).
+
+### Assigning roles to API keys directly using the login policies
+
+1. Prerequisites
+    1. The selected management strategy for your organization must be Login Policies
+    2. You must have appropriate permissions to create or modify login policies
+    3. Understanding of OPA/Rego policy language
+2. Use the `roles` rule to assign roles to users:
+
+```opa
+package spacelift
+
+# Allow API key login
+allow {
+    input.session.login == "api-key-name"
+}
+
+# Assign role to API key
+roles[space][role_id] {
+    input.session.login == "api-key-name"
+}
+```
+
+#### By key name
+
+```opa
+package spacelift
+
+allow { input.session.member }
+
+# Assign role to specific API key
+roles["production"]["deployer-role-id"] {
+    input.session.login == "ci-cd-production"
+}
+
+roles["infrastructure"]["provisioner-role-id"] {
+    input.session.login == "terraform-automation"
+}
+```
+
+#### By key pattern
+
+```opa
+package spacelift
+
+allow { input.session.member }
+
+# Assign roles based on key naming patterns
+roles["production"]["deployer-role-id"] {
+    startswith(input.session.login, "ci-cd-")
+}
+
+roles["monitoring"]["reader-role-id"] {
+    endswith(input.session.login, "-monitoring")
+}
+```
+
+#### Separate keys per environment
+
+```opa
+package spacelift
+
+allow { input.session.member }
+
+# Development environment keys
+roles["development"]["full-deployer-role-id"] {
+    environment_keys := {
+        "ci-cd-dev",
+        "terraform-dev",
+        "automation-dev"
+    }
+    environment_keys[input.session.login]
+}
+
+# Production environment keys (more restrictive)
+roles["production"]["limited-deployer-role-id"] {
+    production_keys := {
+        "ci-cd-prod",
+        "terraform-prod"
+    }
+    production_keys[input.session.login]
+}
+```
+
+#### Multi-environment keys
+
+```opa
+package spacelift
+
+allow { input.session.member }
+
+# Keys that work across multiple environments
+roles[space]["cross-env-role-id"] {
+    cross_env_keys := {"backup-service", "monitoring-agent"}
+    cross_env_keys[input.session.login]
+
+    # Define allowed spaces
+    allowed_spaces := {"development", "staging", "production"}
+    allowed_spaces[space]
+}
+```
+
+#### CI/CD pipeline keys
+
+```opa
+package spacelift
+
+allow { input.session.member }
+
+# GitHub Actions deployment key
+roles["applications"]["github-deployer-role-id"] {
+    input.session.login == "github-actions-deploy"
+}
+
+# GitLab CI deployment key
+roles["applications"]["gitlab-deployer-role-id"] {
+    input.session.login == "gitlab-ci-deploy"
+}
+
+# Jenkins deployment key
+roles["applications"]["jenkins-deployer-role-id"] {
+    input.session.login == "jenkins-deploy"
+}
+```
+
+#### Infrastructure tools
+
+```opa
+package spacelift
+
+allow { input.session.member }
+
+# Terraform Cloud integration
+roles["infrastructure"]["terraform-cloud-role-id"] {
+    input.session.login == "terraform-cloud-integration"
+}
+
+# Ansible automation
+roles["configuration"]["ansible-role-id"] {
+    input.session.login == "ansible-automation"
+}
+
+# Kubernetes operator
+roles["kubernetes"]["k8s-operator-role-id"] {
+    input.session.login == "k8s-spacelift-operator"
+}
+```
+
+#### Conditional API key access
+
+```opa
+package spacelift
+
+allow { input.session.member }
+
+# Time-based API key restrictions
+roles["production"]["time-limited-role-id"] {
+    input.session.login == "scheduled-deployment"
+    is_deployment_window
+}
+
+# Helper rule for deployment windows
+is_deployment_window {
+    now := input.request.timestamp_ns
+    clock := time.clock([now, "UTC"])
+
+    # Allow deployments only during maintenance window
+    # Tuesday and Thursday, 2-4 AM UTC
+    weekday := time.weekday(now)
+    maintenance_days := {"Tuesday", "Thursday"}
+    maintenance_days[weekday]
+
+    clock[0] >= 2
+    clock[0] <= 4
+}
+```
+
+#### IP-restricted API keys
+
+```opa
+package spacelift
+
+allow { input.session.member }
+
+# API keys restricted to specific networks
+roles["production"]["secure-deployer-role-id"] {
+    secure_keys := {"production-deploy", "critical-automation"}
+    secure_keys[input.session.login]
+
+    # Only allow from secure networks
+    is_secure_network
+}
+
+is_secure_network {
+    secure_cidrs := {
+        "10.0.0.0/8",        # Corporate network
+        "192.168.100.0/24"   # Secure CI/CD subnet
+    }
+    secure_cidrs[cidr]
+    net.cidr_contains(cidr, input.request.remote_ip)
+}
+```
+
+### Assigning roles to API keys using IdP groups
+
+See [IdP Group Role Bindings](assigning-roles-groups.md) for details on how to assign roles to IdP groups. Once a role is assigned to an IdP group, all actors (api keys and users that your identity provider reports as being members of that group) will inherit the assigned roles.
+
+## Removing an API key role binding
+
+1. Navigate to API Key Management
+    1. Click your name in the bottom left corner of the Spacelift interface
+    2. Go to **Organization Settings**
+    3. Go to ** **API Keys** in the **Identity Management** section
+    4. Find the API key you want to assign roles to
+    5. Click on the API key row to open its details
+2. Access Role Management
+    1. In the API key details page, click **Manage Roles**
+    2. This opens the role assignment interface for the API key
+3. Remove Role Assignment
+    1. Find the role assignment to remove
+    2. Click the **Unassign** button from the dropdown
+    3. Confirm the removal
+
+## Multiple roles
+
+Actors can have multiple roles across different spaces:
+
+- Different roles in different spaces for varied access levels
+- Multiple roles in the same space (permissions are additive)
+- Roles inherited from group membership plus individual assignments
+
+## Getting role IDs
+
+To use custom roles in login policies, you need their role IDs:
+
+1. Navigate to **Organization Settings** → **Access Control Center** → **Roles**
+2. Click on the custom role you want to use
+3. Click **Copy ID** from the role detail page
+4. Use this ID in your login policy
+
+## Troubleshooting
+
+### Common issues
+
+**API Key Authentication Failures**:
+
+- Verify key is active and not expired
+- Ensure key is being used with correct endpoints
+- Validate key format and encoding
+
+**Permission Denied Errors**:
+
+- Confirm API key has required role assignments
+- Verify role includes necessary actions for the operation
+- Check if operation is being performed in correct space
+- Ensure space exists and API key has access
+
+**Inconsistent Behavior**:
+
+- API key permissions don't require re-authentication
+- Changes to role assignments take effect immediately
+- Check for policy conflicts or syntax errors
+- Validate role IDs are correct in login policies
+
+### Debugging
+
+1. **Test API Key Authentication**: You can create an interactive session with an API key (as if it was a user) to test the key's permissions and actions. To do that, go to
+   `<your-spacelift-subdomain>.spacelift.io/apikeytoken` and enter your API key.
+2. **Check Role Assignments**: Confirm key has correct roles in target spaces
+3. **Validate Actions**: Ensure assigned roles include required permissions
+4. **Test Operations**: Use API key to perform expected operations
+5. **Review Audit Logs**: Check for API key related errors or warnings
+6. **Policy Validation**: If using login policies, verify syntax and logic, use the sample and simulate feature
+
+## Related Topics
+
+- **[Assigning Roles to Users](assigning-roles-users.md)**: Individual user role assignment
+- **[Assigning Roles to IdP Groups](assigning-roles-groups.md)**: Group-based role assignment
+- **[RBAC System](rbac-system.md)**: Understanding Spacelift's RBAC
+- **[API Integration](../../integrations/api.md)**: Using Spacelift's GraphQL API
diff --git a/docs/concepts/authorization/assigning-roles-groups.md b/docs/concepts/authorization/assigning-roles-groups.md
new file mode 100644
index 000000000..6ec6e3672
--- /dev/null
+++ b/docs/concepts/authorization/assigning-roles-groups.md
@@ -0,0 +1,217 @@
+# IdP group role bindings
+
+IdP groups can receive roles through direct group assignment. Assign roles to the entire group, which automatically applies to all members of that group.
+
+## Assigning roles
+
+### Assigning roles to IdP groups using the web UI
+
+1. 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
+    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
+    2. Go to **Organization Settings** → **Identity Management** -> **IdP group mapping**
+3. Create IdP group mapping
+    1. Click **Map IdP group**
+    2. Enter the id of the IdP group (this is the id of the group in your identity provider, e.g., GitHub team slug)
+    3. Select the Role you want to assign to the group
+    4. Select the Space where the group should have this role
+    5. Click **Add** to add role assignment
+    6. Click **Add** to save the group mapping
+4. Access Group Role Management
+    1. Click on the group row in the group list
+    2. Click the **Manage Roles** button
+    3. This opens the group role assignment interface
+
+### Assigning roles to IdP groups using the terraform provider
+
+Refer to the [Spacelift Terraform provider documentation](https://registry.terraform.io/providers/spacelift-io/spacelift/latest/docs/resources/idp_group_mapping) for detailed instructions on creating IdP group mappings programmatically.
+
+### Assigning roles to IdP groups using the login policies
+
+1. Prerequisites
+    1. The selected management strategy for your organization must be Login Policies
+    2. You must have appropriate permissions to create or modify login policies
+    3. Understanding of OPA/Rego policy language
+2. Use the `roles` rule to assign roles to users:
+
+```opa
+package spacelift
+
+allow { input.session.member }
+
+# Assign role based on team membership
+roles[space][role_id] {
+    input.session.teams[_] == "team-name"
+}
+```
+
+#### Individual group assignment
+
+```opa
+package spacelift
+
+allow { input.session.member }
+
+# DevOps team gets platform engineer role
+roles["infrastructure"]["platform-engineer-role-id"] {
+    input.session.teams[_] == "DevOps"
+}
+
+# Frontend team gets developer role
+roles["frontend"]["developer-role-id"] {
+    input.session.teams[_] == "Frontend"
+}
+```
+
+#### Multiple teams, same role
+
+```opa
+package spacelift
+
+allow { input.session.member }
+
+# Define team sets
+developer_teams := {"Frontend", "Backend", "Mobile", "QA"}
+platform_teams := {"DevOps", "SRE", "Platform"}
+
+# Assign developer access
+roles["applications"]["developer-role-id"] {
+    developer_teams[input.session.teams[_]]
+}
+
+# Assign platform access
+roles["infrastructure"]["platform-role-id"] {
+    platform_teams[input.session.teams[_]]
+}
+```
+
+#### Hierarchical team access
+
+```opa
+package spacelift
+
+allow { input.session.member }
+
+# Junior developers: development only
+roles["development"]["junior-dev-role-id"] {
+    input.session.teams[_] == "Junior-Developers"
+}
+
+# Senior developers: development + staging
+roles[space]["senior-dev-role-id"] {
+    input.session.teams[_] == "Senior-Developers"
+    senior_spaces := {"development", "staging"}
+    senior_spaces[space]
+}
+
+# Team leads: all environments
+roles[space]["team-lead-role-id"] {
+    input.session.teams[_] == "Team-Leads"
+    all_spaces := {"development", "staging", "production"}
+    all_spaces[space]
+}
+```
+
+#### Department-based access
+
+```opa
+package spacelift
+
+allow { input.session.member }
+
+# Engineering department base access
+roles["development"]["engineer-role-id"] {
+    input.session.teams[_] == "Engineering"
+}
+
+# Operations department infrastructure access
+roles["infrastructure"]["ops-role-id"] {
+    input.session.teams[_] == "Operations"
+}
+
+# Security department audit access across all spaces
+roles[space]["security-auditor-role-id"] {
+    input.session.teams[_] == "Security"
+    # Apply to all spaces
+    space := input.spaces[_].id
+}
+```
+
+#### Project and functional groups
+
+```opa
+package spacelift
+
+allow { input.session.member }
+
+# Project-based access
+roles["project-alpha"]["developer-role-id"] {
+    input.session.teams[_] == "Project-Alpha-Team"
+}
+
+roles["project-beta"]["developer-role-id"] {
+    input.session.teams[_] == "Project-Beta-Team"
+}
+
+# Functional role overlays
+roles["infrastructure"]["platform-role-id"] {
+    input.session.teams[_] == "Platform-Engineers"
+}
+
+roles[space]["security-role-id"] {
+    input.session.teams[_] == "Security-Champions"
+    # Security champions get audit access everywhere
+    space := input.spaces[_].id
+}
+```
+
+#### Multi-condition team assignment
+
+```opa
+package spacelift
+
+allow { input.session.member }
+
+# Production access requires both team membership and seniority
+roles["production"]["prod-deployer-role-id"] {
+    deployment_teams := {"DevOps", "SRE", "Platform"}
+    deployment_teams[input.session.teams[_]]
+
+    # Additional condition: must also be in senior group
+    input.session.teams[_] == "Senior-Engineers"
+}
+```
+
+## Troubleshooting
+
+### Common issues
+
+**Group Permissions Not Working**:
+
+- Verify group-to-role assignments are correct
+- Check if user is actually a member of the group
+- Ensure user has re-authenticated since group assignment
+- Validate role includes required actions
+
+**Conflicting Group Permissions**:
+
+- Multiple groups can provide different roles
+- Permissions are additive across group memberships
+- Regular audit of group role combinations
+
+### Debugging steps
+
+1. **Verify Group Membership**: Check user is member of expected groups in IdP
+2. **Validate Role Assignment**: Confirm group has correct role assignments
+3. **Review Audit Logs**: Check for group-related permission errors
+
+## Related Topics
+
+- **[Assigning Roles to Users](assigning-roles-users.md)**: Individual user role assignment
+- **[Assigning Roles to API Keys](assigning-roles-api-keys.md)**: Service account permissions
+- **[Login Policies](../policy/login-policy.md)**: Policy-based access control
+- **[Single Sign-On](../../integrations/single-sign-on/README.md)**: IdP integration setup
diff --git a/docs/concepts/authorization/assigning-roles-users.md b/docs/concepts/authorization/assigning-roles-users.md
new file mode 100644
index 000000000..560ea47d1
--- /dev/null
+++ b/docs/concepts/authorization/assigning-roles-users.md
@@ -0,0 +1,248 @@
+# User role bindings
+
+Users can get permissions from three sources:
+
+- **Direct Role Assignment**: Assign roles directly to individual users
+- **IdP Group Assignment**: Assign roles based on group memberships defined in your identity provider
+- **Login Policy**: Use Open Policy Agent (OPA) policies to dynamically assign roles (this can include assignment based on IdP group membership)
+
+!!! note "Immediate Role Changes"
+    Except for Login Policies, role assignments and changes to roles take effect immediately (they force re-authentication if needed).
+
+## Assigning roles
+
+### Assigning roles to users directly using the web UI
+
+1. Prerequisites
+    1. The selected management strategy for your organization must be User Management
+    2. User must be invited to the Spacelift organization
+    3. You must have appropriate permissions to manage user roles
+    4. Target spaces must exist where you want to assign roles
+2. Navigate to User Management:
+    1. Click your name in the bottom left corner of the Spacelift interface
+    2. Select **Organization Settings**
+    3. Navigate to **Users** in the **Identity Management** section
+    4. Find the user you want to modify
+3. Access Role Management
+    1. Click on the user's row in the user list
+    2. Click the **Manage Roles** button
+    3. This opens the role assignment interface
+4. Assign Roles
+    1. **Select Role**: Choose from predefined roles or custom roles
+    2. **Select Space**: Choose the space where the role applies
+    3. **Save Assignment**: Click **Add** to confirm the assignment
+
+### Assigning roles to users directly using the terraform provider
+
+Refer to [Spacelift Terraform provider documentation](https://registry.terraform.io/providers/spacelift-io/spacelift/latest/docs) for more details).
+
+### Assigning roles to users directly using the login policies
+
+1. Prerequisites
+    1. The selected management strategy for your organization must be Login Policies
+    2. You must have appropriate permissions to create or modify login policies
+    3. Understanding of OPA/Rego policy language
+2. Use the `roles` rule to assign roles to users:
+
+```opa
+package spacelift
+
+# Basic login permission
+allow { input.session.member }
+
+# Role assignment syntax
+roles[space_name][role_id] { condition }
+```
+
+#### Individual user assignment
+
+```opa
+package spacelift
+
+allow { input.session.member }
+
+# Assign platform engineer role to specific user
+roles["infrastructure"]["platform-engineer-role-id"] {
+    input.session.login == "alice@company.com"
+}
+
+# Assign multiple roles to same user
+roles["development"]["developer-role-id"] {
+    input.session.login == "alice@company.com"
+}
+
+roles["staging"]["developer-role-id"] {
+    input.session.login == "alice@company.com"
+}
+```
+
+#### Multiple users with same role
+
+```opa
+package spacelift
+
+allow { input.session.member }
+
+# Define user set
+senior_engineers := {
+    "alice@company.com",
+    "bob@company.com",
+    "charlie@company.com"
+}
+
+# Assign role to all users in set
+roles["production"]["senior-developer-role-id"] {
+    senior_engineers[input.session.login]
+}
+```
+
+#### Environment-based access
+
+```opa
+package spacelift
+
+allow { input.session.member }
+
+# Junior developers: development only
+roles["development"]["developer-role-id"] {
+    input.session.teams[_] == "Junior-Developers"
+}
+
+# Senior developers: development + staging
+roles[space]["developer-role-id"] {
+    input.session.teams[_] == "Senior-Developers"
+    environment_spaces := {"development", "staging"}
+    environment_spaces[space]
+}
+
+# Lead developers: all environments
+roles[space]["lead-developer-role-id"] {
+    input.session.teams[_] == "Lead-Developers"
+    all_spaces := {"development", "staging", "production"}
+    all_spaces[space]
+}
+```
+
+#### Time-based access
+
+```opa
+package spacelift
+
+allow { input.session.member }
+
+# Production access only during business hours
+roles["production"]["prod-deployer-role-id"] {
+    input.session.teams[_] == "SRE"
+    is_business_hours
+}
+
+# Helper rule for business hours
+is_business_hours {
+    now := input.request.timestamp_ns
+    clock := time.clock([now, "America/Los_Angeles"])
+    weekday := time.weekday(now)
+
+    # Monday through Friday, 9 AM to 5 PM
+    not weekend[weekday]
+    clock[0] >= 9
+    clock[0] <= 17
+}
+
+weekend := {"Saturday", "Sunday"}
+```
+
+#### IP-based access
+
+```opa
+package spacelift
+
+allow { input.session.member }
+
+# Sensitive operations only from office network
+roles["production"]["admin-role-id"] {
+    input.session.teams[_] == "DevOps"
+    is_office_network
+}
+
+# Helper rule for office network
+is_office_network {
+    office_networks := {
+        "192.168.1.0/24",
+        "10.0.0.0/8"
+    }
+    office_networks[network]
+    net.cidr_contains(network, input.request.remote_ip)
+}
+```
+
+### Assigning roles to users via IdP groups
+
+See [IdP Group Role Bindings](assigning-roles-groups.md) for details on how to assign roles to IdP groups. Once a role is assigned to an IdP group, all actors (api keys and users that your identity provider reports as being members of that group) will inherit the assigned roles.
+
+## Removing a user role binding
+
+1. Navigate to User Management:
+    1. Click your name in the bottom left corner of the Spacelift interface
+    2. Select **Organization Settings**
+    3. Navigate to **Users** in the **Identity Management** section
+    4. Find the user you want to modify
+2. Access Role Management
+    1. Click on the user's row in the user list
+    2. Click the **Manage Roles** button
+    3. This opens the role assignment interface
+3. Remove Role Assignment
+    1. Find the role assignment to remove
+    2. Click the **Unassign** button from the dropdown
+    3. Confirm the removal
+
+## Multiple roles
+
+Actors can have multiple roles across different spaces:
+
+- Different roles in different spaces for varied access levels
+- Multiple roles in the same space (permissions are additive)
+- Roles inherited from group membership plus individual assignments
+
+## Getting role IDs
+
+To use custom roles in login policies, you need their role IDs:
+
+1. Navigate to **Organization Settings** → **Access Control Center** → **Roles**
+2. Click on the custom role you want to use
+3. Click **Copy ID** from the role detail page
+4. Use this ID in your login policy
+
+## Troubleshooting
+
+### Common issues
+
+**User Cannot See Resources**:
+
+- Verify user has `space:read` action
+- Check if user is assigned to correct space
+
+**Role Assignment Not Taking Effect**:
+
+- Check if login policy has syntax errors
+- Verify role ID is correct in login policies
+
+**Permission Denied Errors**:
+
+- Verify user has required actions for the operation
+- Check if operation is being performed in correct space
+- Confirm role includes necessary permissions
+
+**Login Policy Not Working**:
+
+- Check policy syntax for errors
+- Verify input data structure matches policy conditions
+- Use policy sampling to debug input data
+- Check for typos in team names or user logins
+- Check for case sensitivity in team names and user logins
+
+## Related Topics
+
+- **[Assigning Roles to IdP Groups](assigning-roles-groups.md)**: Group-based role assignment
+- **[Assigning Roles to API Keys](assigning-roles-api-keys.md)**: Service account permissions
+- **[RBAC System](rbac-system.md)**: Understanding Spacelift's RBAC
+- **[User Management](../user-management/README.md)**: User invitation and management
diff --git a/docs/concepts/authorization/rbac-system.md b/docs/concepts/authorization/rbac-system.md
new file mode 100644
index 000000000..bb5131d5f
--- /dev/null
+++ b/docs/concepts/authorization/rbac-system.md
@@ -0,0 +1,282 @@
+# Role-Based Access Control (RBAC)
+
+Up until recently, Spacelift used **legacy system roles** with broad roles (Reader, Writer, Admin) to manage user permissions.
+This approach worked for many organizations but lacked the granularity and flexibility needed for modern infrastructure management.
+With the introduction of the **Custom RBAC** system, Spacelift has transformed how permissions are managed, enabling a more
+fine-grained, composable approach to access control.
+
+## Custom RBAC vs legacy system roles
+
+### Legacy system roles (previous approach)
+
+The legacy system used three broad roles:
+
+- **Reader**: View-only access to resources
+- **Writer**: Reader permissions + ability to trigger runs and modify environment variables
+- **Admin**: Writer permissions + ability to create/modify stacks and attachable entities
+
+!!! note "Migration to Custom RBAC"
+    Existing legacy system role assignments have been automatically migrated to equivalent custom RBAC roles:
+
+    | Legacy Role | RBAC Equivalent |
+    |-------------|-----------------|
+    | Reader      | Space Reader    |
+    | Writer      | Space Writer    |
+    | Admin       | Space Admin     |
+
+### Custom RBAC (current approach)
+
+Custom RBAC decomposes these broad roles into **individual, composable actions**.
+
+!!! example "Custom RBAC Example"
+    Instead of giving an actor, like an API key, full **Writer** access (which includes many permissions that are not needed), you can create a custom "Deployment Operator" role with just:
+
+    - `run:trigger`: Can trigger stack runs
+    - `run:read`: Can view run details
+
+    This provides exactly the access needed for deployment operations without broader permissions.
+
+## Core architecture
+
+In Spacelift's RBAC system, **Actors** are entities that perform **Actions** on **Subjects** within **Spaces**. This architecture allows for precise control over who can do what, where, and how.
+
+### Actors: who performs actions
+
+#### Users
+
+Individual team members who are authenticated through your identity provider (GitHub, GitLab, Microsoft, Google, or SAML/OIDC
+SSO).
+
+##### User patterns
+
+- Use IdP groups for role assignment when possible
+- Limit individual user role assignments to exceptional cases
+- Regular access reviews and cleanup
+
+#### API Keys
+
+Programmatic access tokens for automation and CI/CD integration.
+
+##### API key patterns
+
+- Create purpose-specific keys with minimal required permissions
+- Use specific custom roles rather than broad predefined roles
+- Use environment-specific keys rather than shared keys
+- Use descriptive names that indicate purpose (e.g., "terraform-ci-prod")
+- Include environment or project context in the name
+- Implement key rotation policies
+- Document the purpose and owner of each API key
+- Monitor API key usage through audit trails
+
+#### IdP Groups
+
+Groups of users as defined by your identity provider.
+
+##### Examples of group sources
+
+**GitHub Teams**:
+
+- Passed in the users' token
+
+**SAML/OIDC Groups**:
+
+- Defined by your enterprise identity provider
+- Mapped through SAML assertions or OIDC claims
+- Group membership determined by your IdP's group policies
+
+##### IdP group patterns
+
+**Functional Groups**:
+Organize groups by job function across the organization:
+
+- `platform-engineers` → Full infrastructure management
+- `application-developers` → Deployment capabilities only
+- `security-auditors` → Read-only access across all spaces
+
+**Project Groups**:
+Organize groups by project or product:
+
+- `project-alpha-team` → Full access to "Project Alpha" space
+- `project-beta-team` → Full access to "Project Beta" space
+
+**Hybrid Approach**:
+Combine functional and project-based groups:
+
+- Base permissions from functional groups
+- Additional project-specific permissions from project groups
+
+### Actions: the building blocks of permissions
+
+Actions are the smallest unit of permission granularity in Spacelift's RBAC system. Each action defines a specific
+operation that can be performed.
+
+#### Action examples
+
+| Action           | Description                | Legacy Equivalent |
+|------------------|----------------------------|-------------------|
+| `run:trigger`    | Trigger stack runs         | Writer            |
+| `stack:manage`   | Create and modify stacks   | Admin             |
+| `stack:delete`   | Delete stacks              | Admin             |
+| `context:read`   | View contexts              | Reader            |
+| `context:manage` | Create and modify contexts | Admin             |
+| `space:read`     | View space contents        | Reader            |
+| `space:manage`   | Manage space settings      | Admin             |
+
+!!! note "Expanding Action Catalog"
+    The RBAC system supports a limited, but expanding set of actions. Spacelift continuously adds new actions based on user feedback and use cases.
+
+### Subjects: what actions are performed on
+
+Subjects are the resources that actors interact with, for example:
+
+- **Stacks**: Infrastructure definitions, runs, and associated metadata
+- **Contexts**: Environment variables, mounted files, and configuration collections
+- **Policies**: Rules governing Spacelift behavior (approval, notification, etc.)
+
+!!! warning "Space-Level Granularity"
+    Currently, RBAC operates at the **space level**. All roles are bound to specific spaces and apply equally to all subjects within that space. Entity-level granularity (e.g., permissions for individual stacks) is not yet supported.
+
+#### Stack access patterns
+
+**Development Stacks**:
+
+- Developers need full management capabilities
+- Frequent deployments and experimentation
+- Less restrictive approval requirements
+
+**Production Stacks**:
+
+- Limited management access to senior engineers
+- Strict approval workflows
+- Enhanced audit and monitoring
+
+**Shared Infrastructure Stacks**:
+
+- Platform team management
+- Application team read access
+- Cross-team coordination requirements
+
+#### Policy access patterns
+
+**Centralized Governance**:
+
+- Security team manages all policies
+- Consistent rules across the organization
+- Limited policy creation permissions
+
+**Federated Governance**:
+
+- Teams manage policies for their own spaces
+- Organization-wide baseline policies
+- Team-specific additional policies
+
+### Spaces: the scope of permissions
+
+All RBAC roles are **space-bound**, meaning:
+
+- Roles are assigned to specific spaces
+- Permissions apply to all subjects within that space
+- Users need appropriate roles in each space they need to access
+
+#### Space hierarchy
+
+Spaces can be organized hierarchically to reflect your organizational structure:
+
+```text
+Root Space
+├── Infrastructure (Platform team management)
+│   ├── Networking
+│   ├── Security
+│   └── Monitoring
+├── Applications (Application teams)
+│   ├── Frontend
+│   ├── Backend
+│   └── Mobile
+└── Sandbox (Development and testing)
+```
+
+#### Space design patterns
+
+**Isolation Requirements**:
+
+- Separate spaces for different environments (dev/staging/prod)
+- Separate spaces for different teams or projects
+- Separate spaces for different compliance requirements
+
+**Permission Boundaries**:
+
+- Align space boundaries with permission requirements
+- Consider who needs access to what resources
+- Plan for space hierarchy and inheritance patterns
+
+## Roles
+
+### Predefined roles
+
+Spacelift provides three predefined roles (they correspond to the legacy system roles):
+
+#### Space reader
+
+**Actions**: Basic read permissions
+
+- View stacks, contexts, policies, and runs
+- Add comments to runs for feedback
+- Cannot trigger actions or modify resources
+- Equivalent to legacy **Reader** role
+
+#### Space writer
+
+**Actions**: Space Reader + multiple execution permissions
+
+- All Space Reader permissions
+- Trigger stack runs
+- Execute tasks
+- Modify stack environment variables
+- Equivalent to legacy **Writer** role
+
+#### Space admin
+
+**Actions**: Space Writer + management permissions
+
+- All Space Writer permissions
+- Create and modify stacks
+- Create and modify contexts and policies
+- Manage space settings (when assigned to specific space)
+- 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.
+
+### Custom roles
+
+#### Creating custom roles using the web UI
+
+1. Go to **Organization Settings** → **Access Control Center** → **Roles**
+
+2. Click **Create Role** to start defining a new role
+
+3. **Define Role Properties**:
+    - **Name**: Descriptive role name (e.g., "Infrastructure Developer")
+    - **Description**: Clear explanation of the role's purpose
+    - **Actions**: Select specific permissions needed
+
+!!! note "Read Access Baseline"
+    The `space:read` action is required to view any subjects within a space—without it, users cannot see resources even if they have other permissions for them.
+
+#### Creating custom roles using the terraform provider
+
+Refer to the [Spacelift Terraform provider documentation](https://registry.terraform.io/providers/spacelift-io/spacelift/latest/docs/resources/role) for detailed instructions on creating custom roles programmatically.
+
+## Role bindings (assigning roles to actors)
+
+### User role bindings
+
+Refer to [Assigning Roles to Users](../authorization/assigning-roles-users.md) for detailed instructions on how to assign roles to individual users.
+
+### API key role bindings
+
+Refer to [Assigning Roles to API Keys](../authorization/assigning-roles-api-keys.md) for detailed instructions on how to assign roles to API keys.
+
+### IdP group role bindings
+
+Refer to [Assigning Roles to Groups](../authorization/assigning-roles-groups.md) for detailed instructions on how to assign roles to IdP groups.
diff --git a/docs/concepts/policy/login-policy.md b/docs/concepts/policy/login-policy.md
index a505ad8f1..7d0d9a8e4 100644
--- a/docs/concepts/policy/login-policy.md
+++ b/docs/concepts/policy/login-policy.md
@@ -5,9 +5,16 @@
 
 ## Purpose
 
-Login policies allow users to log in to the Spacelift account and can grant admin privileges. Unlike all other policy types, login policies are global and can't be attached to individual stacks. They take effect immediately once they're created and affect all future login attempts.
+Login policies provide policy-as-code authorization for Spacelift, allowing users to log in and
+assign [RBAC roles](../authorization/README.md) programmatically. Unlike all other policy types, login policies are
+global and can't be attached to individual stacks. They take effect immediately once they're created and affect all
+future login attempts.
 
-API Keys are treated as virtual users and evaluated with login policy unless they are in the "root" space set with an admin key.
+Login policies are one of two authorization strategies available in
+Spacelift. The other is [User Management](../user-management/) for GUI-based permission management.
+
+API Keys are treated as virtual users and evaluated with login policy unless they are in the "root" space set with an
+admin key.
 
 !!! tip
     GitHub or [SSO](../../integrations/single-sign-on/README.md) admins and private account owners always have admin access to their respective Spacelift accounts, regardless of login policies, so login policy errors can't lock everyone out of the account.
@@ -15,13 +22,26 @@ API Keys are treated as virtual users and evaluated with login policy unless the
 !!! warning
     Any changes (create, update, or delete) made to a login policy will invalidate **all** active sessions except the session making the change.
 
+### Authentication rules
+
 A login policy can define the following types of boolean rules:
 
 - **allow**: Allows the user to log in as a _non-admin_
 - **admin**: Allows the user to log in as an account-wide _admin_. You don't need to explicitly **allow** admin users
 - **deny**: Denies the login attempt, regardless of other (**allow** and **admin**) rules
 - **deny_admin**: Denies the current user **admin** access to the stack, regardless of other rules
-- **space_admin/space_write/space_read**: Manages access levels to spaces. Learn more in [Spaces Access Control](../spaces/access-control.md)
+
+### RBAC Role Assignment
+
+- **roles**: Assigns [RBAC roles](../authorization/rbac-system.md) to users for specific spaces. This is the modern
+  approach for fine-grained permissions.
+
+### Legacy space rules (deprecated)
+
+space_admin/space_write/space_read:
+
+!!! warning "Legacy Space Rules"
+    The `space_admin`, `space_write`, and `space_read` rules are deprecated. Use the `roles` rule to assign [RBAC roles](../authorization/rbac-system.md) for better granularity and security.
 
 If no rules match, the default action will be to **deny** a login attempt.
 
@@ -45,13 +65,17 @@ Each policy request will receive this data input:
     "login": "string - username of the user trying to log in",
     "member": "boolean - is the user a member of the account",
     "name": "string - full name of the user trying to log in - may be empty",
-    "teams": ["string - names of teams the user is a member of"]
+    "teams": [
+      "string - names of teams the user is a member of"
+    ]
   },
   "spaces": [
     {
       "id": "string - ID of the space",
       "name": "string - name of the space",
-      "labels": ["string - label of the space"]
+      "labels": [
+        "string - label of the space"
+      ]
     }
   ]
 }
@@ -97,7 +121,7 @@ Two fields in the `session` object require further explanation: _member_ and _te
 ## Login policy examples
 
 !!! abstract "Example Policies Library"
-    We maintain a [library of example policies](https://github.com/spacelift-io/spacelift-policies-example-library/tree/main/examples/login){: rel="nofollow"} that are ready to use as-is or tweak to meet your specific needs.
+    We maintain a [library of example policies](https://github.com/spacelift-io/spacelift-policies-example-library/tree/main/examples/login){:rel="nofollow"} that are ready to use as-is or tweak to meet your specific needs.
 
     If you can't find what you're looking for below or in the library, please reach out to [Spacelift support](../../product/support/README.md#contact-support) and we will craft a policy to meet your needs.
 
diff --git a/docs/concepts/spaces/access-control.md b/docs/concepts/spaces/access-control.md
index b83fbc409..90820b384 100644
--- a/docs/concepts/spaces/access-control.md
+++ b/docs/concepts/spaces/access-control.md
@@ -1,75 +1,115 @@
-# Access Control
+# Access control
 
-With Spaces, the whole permission management process is done within [Login policies](../policy/login-policy.md) or [User Management](../user-management/) depending on your account strategy, you can then specify what type of role a user gets within the given spaces.
+Spaces provide the organizational structure for Spacelift's [RBAC system](../authorization/README.md). Permission
+management is handled through [Login policies](../policy/login-policy.md) or [User Management](../user-management/)
+depending on your authorization strategy. All roles are assigned to
+specific spaces, providing precise control over who can access what resources.
 
-## Roles
+## Roles and RBAC
 
-There are 3 roles that you can assign to users on a space-by-space basis:
+### Predefined roles
 
-- **Read** - cannot create or modify neither stacks nor any attachable entities, but can view them and add comments to runs, providing a central place for shared feedback without affecting runs.
-- **Write** - an extension to **Read**, as it can actually trigger runs in the stacks it sees.
-- **Admin** - can create and modify stacks and attachable entities, as well as trigger runs.
+Spacelift provides three predefined roles that can be assigned to users on a space-by-space basis:
 
-A special case is someone who is given Admin permissions to the `root` space - we would call that person a Root Space Admin.
-Any Root Space Admin is perceived to be an admin of the whole account. Only they can modify the space tree or access account-wide settings.
+- **Space Reader** - View-only access to resources within the space, can add comments to runs for collaboration
+- **Space Writer** - Space Reader permissions + ability to trigger runs and modify environment variables
+- **Space Admin** - Space Writer permissions + ability to create and modify stacks and attachable entities
 
-A comparison table of what users with given roles are capable of can be found below.
+These predefined roles correspond to the legacy system roles (Read/Write/Admin) and provide a simple starting point for
+organizations new to RBAC.
 
-| Action\Who                    | Root Space Admin | Admin | Writer | Reader |
-|-------------------------------|------------------|-------|--------|--------|
-| Setup SSO                     | ✅                | ❌     | ❌      | ❌      |
-| Setup VCS                     | ✅                | ❌     | ❌      | ❌      |
-| Manage Sessions               | ✅                | ❌     | ❌      | ❌      |
-| Manage Login Policies         | ✅                | ❌     | ❌      | ❌      |
-| Manage Audit Trails           | ✅                | ❌     | ❌      | ❌      |
-| Manage Spaces                 | ✅                | ✅     | ❌      | ❌      |
-| Manage Stack Config Settings  | ✅                | ✅     | ❌      | ❌      |
-| Manage Worker Pools, Contexts | ✅                | ✅     | ❌      | ❌      |
-| Manage Stack Env Vars         | ✅                | ✅     | ✅      | ❌      |
-| Trigger runs                  | ✅                | ✅     | ✅      | ❌      |
-| View Stacks                   | ✅                | ✅     | ✅      | ✅      |
-| View Spaces                   | ✅                | ✅     | ✅      | ✅      |
-| View Worker Pools, Contexts   | ✅                | ✅     | ✅      | ✅      |
+### Custom roles
 
-## Login Policies
+Beyond predefined roles, you can create [custom roles](../authorization/rbac-system.md#custom-roles) with precisely
+tailored permissions:
 
-The way you can control access to Spaces in your Spacelift account is by using [Login policies](../policy/login-policy.md).
+- **Granular Actions**: Compose roles from specific actions like `run:trigger`, `stack:manage`, `context:read`
+- **Business-Aligned**: Match roles to your organizational structure and job functions
+- **Principle of Least Privilege**: Grant exactly the permissions needed, nothing more
 
-We have introduced new rules that allow you to assign access to spaces:
+!!! example "Custom Role Example"
+    Instead of giving someone full **Space Admin** access, create a custom "Infrastructure Developer" role with just:
 
-- **space_read**
-- **space_write**
-- **space_admin**
+    - `space:read`: View space contents
+    - `stack:read`: Understand configurations
+    - `run:trigger`: Deploy changes
+    - `run:read`: Monitor deployments
 
-Here is a valid login policy that uses all of them:
+A "Root Space Admin" is a user given administrative permissions to the `root` space, which is the top-level space in Spacelift's hierarchy. This gives them special permissions and allows them to manage the entire account, including modifying the space tree and accessing account-wide settings.
+
+### Permission comparison
+
+| Action\Role                   | Root Space Admin | Space Admin | Space Writer | Space Reader |
+|-------------------------------|------------------|-------------|--------------|--------------|
+| Setup SSO                     | ✅                | ❌           | ❌            | ❌            |
+| Setup VCS                     | ✅                | ❌           | ❌            | ❌            |
+| Manage Sessions               | ✅                | ❌           | ❌            | ❌            |
+| Manage Login Policies         | ✅                | ❌           | ❌            | ❌            |
+| Manage Audit Trails           | ✅                | ❌           | ❌            | ❌            |
+| Manage Spaces                 | ✅                | ✅*          | ❌            | ❌            |
+| Manage Stack Config Settings  | ✅                | ✅           | ❌            | ❌            |
+| Manage Worker Pools, Contexts | ✅                | ✅           | ❌            | ❌            |
+| Manage Stack Env Vars         | ✅                | ✅           | ✅            | ❌            |
+| Trigger runs                  | ✅                | ✅           | ✅            | ❌            |
+| View Stacks                   | ✅                | ✅           | ✅            | ✅            |
+| View Spaces                   | ✅                | ✅           | ✅            | ✅            |
+| View Worker Pools, Contexts   | ✅                | ✅           | ✅            | ✅            |
+
+*Only when assigned to the specific space
+
+## Authorization methods
+
+### User management
+
+The [User Management](../user-management/) interface provides a way to assign roles to users, groups, and API
+keys:
+
+1. Navigate to **Organization Settings** → **Identity Management**
+2. Select **Users**, **IdP group mapping**, or **API keys**
+3. Assign predefined or custom roles to specific spaces
+
+See [assigning roles to users](../authorization/assigning-roles-users.md) for detailed instructions.
+
+### Login policies (policy-as-code)
+
+[Login policies](../policy/login-policy.md) enable programmatic role assignment using OPA/Rego:
+
+#### Legacy space rules (deprecated)
+
+The legacy space rules are deprecated in favor of RBAC roles:
+
+- **space_read** → Use RBAC roles with `space:read` action
+- **space_write** → Use RBAC roles with appropriate write actions
+- **space_admin** → Use RBAC roles with management actions
+
+#### RBAC Role Assignment
+
+Use the `roles` rule to assign RBAC roles in login policies:
 
 ```opa
 package spacelift
 
-developers := { "bob" }
-login   := input.session.login
-is_developer { developers[login] }
-allow { is_developer }
+# Basic login permissions
+allow { input.session.member }
 
-# Let's give every developer read access to any space
-space_read[space.id] {
-  space := input.spaces[_]
-  is_developer
+# Assign RBAC roles using role IDs
+roles["development"]["developer-role-id"] {
+    input.session.teams[_] == "Frontend"
 }
 
-# Assign write role to developers for spaces with "developers-are-writers" label
-space_write[space.id] {
-  space := input.spaces[_]
-  space.labels[_] == "developers-are-writers"
-  is_developer
+roles["infrastructure"]["platform-engineer-role-id"] {
+    input.session.teams[_] == "DevOps"
 }
 
-# Assign admin role for the root space for anyone in the admin team
-space_admin["root"] {
-  input.session.teams[_] == "admin"
+# Assign admin role for root space
+roles["root"]["space-admin-role-id"] {
+    input.session.teams[_] == "Admin"
 }
 ```
 
+!!! note "Getting Role IDs"
+    To use custom roles in login policies, copy the role ID from **Organization Settings** → **Access Control Center** → **Roles** → select role → copy ID.
+
 !!! warning
     - Please note that Login policies are only allowed to be created in the `root` space, therefore only `root` space admins and administrative stacks, as well as `legacy` space administrative stacks can create or modify them.
     - A logged-in user's access levels only get updated when they log out and in again, so newly added spaces might not be visible to some users. An exception is that the space's creator immediately gets access to it.
@@ -101,3 +141,10 @@ Next, the user was given **Admin** access to the `admin access space` space. Reg
 This makes sense, as we want to allow admins to still manage their spaces subtree even if they want to disable resource sharing between some spaces.
 
 Finally, the user was given **Read** access to the `read access space` space. Because inheritance is off, they did not receive **Read** access to the `legacy` space.
+
+## Related topics
+
+- **[Authorization & RBAC](../authorization/README.md)**: Complete guide to Spacelift's authorization system
+- **[RBAC System](../authorization/rbac-system.md)**: Understanding roles, actions, and actors
+- **[User Management](../user-management/)**: GUI-based permission management
+- **[Login Policies](../policy/login-policy.md)**: Policy-as-code authorization
diff --git a/docs/concepts/user-management/README.md b/docs/concepts/user-management/README.md
index df2b45bf6..688d07ad7 100644
--- a/docs/concepts/user-management/README.md
+++ b/docs/concepts/user-management/README.md
@@ -1,18 +1,10 @@
-# User Management
+# User management
 
 Spacelift is made for collaboration. In order to collaborate, you need collaborators. User Management is an easy way to invite new members to your organization and manage their permissions, together with third-party integrations and group access. If you prefer to write a policy rather than using our UI, please check out [Login Policies](../policy/login-policy.md).
 
 !!! warning
     User Management doesn't affect GitHub organization or [SSO](../../integrations/single-sign-on/README.md) admins and private account owners who always get admin access to their respective Spacelift accounts. This is to avoid a situation where a mistake in User Management locks out everyone from the account.
 
-## Roles
-
-User Management works by setting one of the following roles for users, groups and [integrations](../user-management/admin.md#slack-integration) for selected [Spaces](../spaces/README.md).
-
-- **Read** - cannot create or modify stacks or any attachable entities, but can view them
-- **Write** - can perform actions like triggering runs, but cannot create or modify Spacelift resources
-- **Admin** - can create and modify stacks and attachable entities, as well as trigger runs
-
 ## User
 
 Users are individuals invited through their email and authenticated using your account's Identity Provider. Users can have personal permissions assigned.
@@ -21,9 +13,14 @@ Users are individuals invited through their email and authenticated using your a
 
 Group is a group of users as provided by your Identity Provider. If you assign permissions to a Group, all users that your Identity Provider reports as being members of a given group will have the same access, unless the user's permissions are higher than the ones they would get from being a member of a Group.
 
+## Roles in User Management
+
+User Management leverages Spacelift's [RBAC system](../authorization/rbac-system.md) to assign roles to users, groups for selected [Spaces](../spaces/README.md).
+
 ## Invitation process
 
-New users can be invited through email by account admins and owners. Detailed instructions can be found on [the Admin page](admin.md) of this documentation.
+New users can be invited through email by account admins and owners. Detailed instructions can be found
+on [the Admin page](admin.md).
 
 Once a user is invited, they will receive an email from Spacelift that will take them to your identity provider page.
 
@@ -34,3 +31,9 @@ Once the user authenticates with your identity provider, they will be redirected
 ## Migrating from Login Policy
 
 If you were previously using [Login Policy](../policy/login-policy.md) you can queue invites to User Management for your users while still having Login Policy enabled. Once you switch to the User Management strategy, the invites will be sent to your users' emails and allow them to sign in through your Identity Provider. Remember, that you can always go back if it turns out something was misconfigured.
+
+## Related topics
+
+- **[Authorization & RBAC](../authorization/README.md)**: Complete guide to Spacelift's authorization system
+- **[Assigning Roles to Users](../authorization/assigning-roles-users.md)**: Detailed role assignment guide
+- **[Assigning Roles to Groups](../authorization/assigning-roles-groups.md)**: Team-based permission management
diff --git a/docs/installing-spacelift/changelog.md b/docs/installing-spacelift/changelog.md
index 87722440d..5d893c9e4 100644
--- a/docs/installing-spacelift/changelog.md
+++ b/docs/installing-spacelift/changelog.md
@@ -280,7 +280,7 @@ Although we have safeguards in place to ensure the migration is successful, we r
 - Disabled the rate limiting for [policy sampling](../concepts/policy/README.md#sampling-policy-inputs)
 - Added LaunchPad, a dashboard for new Spacelift users that provides a guided tour of the platform
 - Added support for [OPA v0.64](https://github.com/open-policy-agent/opa/releases/tag/v0.64.0)
-- Support for [moved](https://developer.hashicorp.com/terraform/language/modules/develop/refactoring) and [imported](https://developer.hashicorp.com/terraform/language/import) Terraform resources
+- Support for moved and [imported](https://developer.hashicorp.com/terraform/language/import) Terraform resources
 - Installation script:
     - [We added support for defining custom retention periods for all of the S3 buckets.](./cloudformation/install.md#s3-config) If you don't specify it, they remain untouched.
 
diff --git a/nav.yaml b/nav.yaml
index 2241c7747..6781efc1e 100644
--- a/nav.yaml
+++ b/nav.yaml
@@ -80,6 +80,13 @@ nav:
           - concepts/spaces/migrating-out-of-the-legacy-space.md
           - concepts/spaces/best-practices.md
           - concepts/spaces/allowing-non-root-admins-to-manage-spaces.md
+      - Authorization & RBAC:
+          - concepts/authorization/README.md
+          - concepts/authorization/rbac-system.md
+          - Assigning Roles:
+              - concepts/authorization/assigning-roles-users.md
+              - concepts/authorization/assigning-roles-groups.md
+              - concepts/authorization/assigning-roles-api-keys.md
       - User Management:
           - concepts/user-management/README.md
           - concepts/user-management/admin.md