diff --git a/docs/assets/screenshots/blueprint_preview.png b/docs/assets/screenshots/blueprint_preview.png
index 67985342a..ac6863a71 100644
Binary files a/docs/assets/screenshots/blueprint_preview.png and b/docs/assets/screenshots/blueprint_preview.png differ
diff --git a/docs/assets/screenshots/creating-login-policy.png b/docs/assets/screenshots/creating-login-policy.png
new file mode 100644
index 000000000..4a9b093a3
Binary files /dev/null and b/docs/assets/screenshots/creating-login-policy.png differ
diff --git a/docs/assets/screenshots/new-api-create-1.png b/docs/assets/screenshots/new-api-create-1.png
new file mode 100644
index 000000000..b3ec9aa65
Binary files /dev/null and b/docs/assets/screenshots/new-api-create-1.png differ
diff --git a/docs/assets/screenshots/new-api-create-2.png b/docs/assets/screenshots/new-api-create-2.png
new file mode 100644
index 000000000..904b310ec
Binary files /dev/null and b/docs/assets/screenshots/new-api-create-2.png differ
diff --git a/docs/assets/screenshots/new-api-create-3.png b/docs/assets/screenshots/new-api-create-3.png
new file mode 100644
index 000000000..9dc19a63a
Binary files /dev/null and b/docs/assets/screenshots/new-api-create-3.png differ
diff --git a/docs/assets/screenshots/slack-access-form.png b/docs/assets/screenshots/slack-access-form.png
new file mode 100644
index 000000000..b794d5412
Binary files /dev/null and b/docs/assets/screenshots/slack-access-form.png differ
diff --git a/docs/assets/screenshots/slack-integration.png b/docs/assets/screenshots/slack-integration.png
new file mode 100644
index 000000000..db31b4ade
Binary files /dev/null and b/docs/assets/screenshots/slack-integration.png differ
diff --git a/docs/assets/screenshots/user-management/confirmation-email.png b/docs/assets/screenshots/user-management/confirmation-email.png
new file mode 100644
index 000000000..950956b04
Binary files /dev/null and b/docs/assets/screenshots/user-management/confirmation-email.png differ
diff --git a/docs/assets/screenshots/user-management/confirmation-landing.png b/docs/assets/screenshots/user-management/confirmation-landing.png
new file mode 100644
index 000000000..0b2fe38e0
Binary files /dev/null and b/docs/assets/screenshots/user-management/confirmation-landing.png differ
diff --git a/docs/assets/screenshots/user-management/invitation-email.png b/docs/assets/screenshots/user-management/invitation-email.png
new file mode 100644
index 000000000..289a10a5e
Binary files /dev/null and b/docs/assets/screenshots/user-management/invitation-email.png differ
diff --git a/docs/concepts/user-management/README.md b/docs/concepts/user-management/README.md
new file mode 100644
index 000000000..df3b47a7e
--- /dev/null
+++ b/docs/concepts/user-management/README.md
@@ -0,0 +1,36 @@
+# 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.
+
+## IdP group mapping
+
+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.
+
+## 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.
+
+Once a user is invited, they will receive an email from Spacelift that will take them to your identity provider page.
+
+
+
+Once the user authenticates with your identity provider, they will be redirected to application.
+
+## 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.
diff --git a/docs/concepts/user-management/admin.md b/docs/concepts/user-management/admin.md
new file mode 100644
index 000000000..e4d897ada
--- /dev/null
+++ b/docs/concepts/user-management/admin.md
@@ -0,0 +1,84 @@
+# Admin / Owner
+
+Users with **Owner** and **root Admin** roles have access to **Organization settings**. This means they can manage access for the rest of the collaborators within your Spacelift account. The following article details the configuration options and user invitation procedures available to them.
+
+## Access settings
+
+Access settings can be found by clicking the button in the lower-left corner with your avatar and selecting **Organization settings**.
+
+## Select your Management Strategy
+
+Account administrators can choose between User management and Login policy strategies in **Management strategy** tab. Once selected, the rules from the other strategy no longer apply.
+
+!!! warning
+ Strategy selection does not 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 bad management strategy locks out everyone from the account.
+
+!!! danger
+ Changing your Management Strategy will invalidate all active sessions, except the session making the change.
+
+## Users
+
+The user list can be accessed by selecting **Users** tab in the left drawer.
+
+The user list consists of all individuals who have or had access to your account through the User Management access strategy.
+
+Below is a longer description of fields that we believe might not be obvious at first glance.
+
+### Role
+
+The displayed Role badge is different than the space access role. It describes the user's role within the organization, instead of specific space permissions. This badge can have one of three values:
+
+- **OWNER** - account admin, SSO admin or GitHub organization being the owner of an account.
+- **ADMIN** - a user who has direct admin permissions to the **root** space. This badge does not take group or integration permissions into account.
+- **USER** - users without admin permissions to the **root** space.
+
+### Space
+
+The number of spaces that the user has at least read access to. This only takes direct user permissions into account, and does not include permissions inherited from groups.
+
+### Group
+
+The number of groups that the user was a member of during the last login, as reported by the account's Identity Provider.
+
+### Login method
+
+The Identity Provider that was used for authenticating the user. It will usually be the same as the account's current Identity Provider, but on a rare occasion that Identity Provider changes, this will allow for auditing old access or transferring permissions to users within the new Identity Provider.
+
+### Status
+
+- **QUEUED** - user invitation was issued and will be sent once Management Strategy is changed from Login Policy to User Management
+- **PENDING** - user invitation was sent and can be accepted or the user still needs to confirm their ownership of the invitation email with a code found in the confirmation code email.
+- **EXPIRED** - user invitation was sent, but the user did not accept it before it expired. Spacelift invitation is active for 24h. A new invitation must be issued for a user to be able to access your Spacelift account.
+- **ACTIVE** - user has accepted an invitation to your Spacelift account and has permissions set in User Management as long as User Management is the selected access strategy.
+- **INACTIVE** - the user was previously able to access your Spacelift account, but the Identity Provider for your account has changed. The user needs to be invited again and must login through the new Identity Provider to continue using Spacelift.
+
+## Inviting new users
+
+To invite new users to your account, click on the 'Invite user' button located in the top right corner. You will be able to send them an email invitation link and determine their access level during the invitation process.
+
+### Resending user invitation
+
+If a user did not receive an invitation email or their invitation has expired, you can select **Resend invite** from the three dots menu. Issuing a new invite is not possible if a pending or expired invite for a given email address already exists.
+
+### Revoking user invitation
+
+At any time you can revoke a user invitation by choosing **Revoke invite** from the three dots menu. Once the invitation is revoked, it will no longer allow user access to your account. If you wish to invite a user with a given email at a later date, you can issue a new invitation.
+
+## Managing user access
+
+You can manage access rules for anyone who logs into your account by selecting the **Access details** option from the three dots menu.
+
+### Slack integration
+
+After setting up the [Slack integration](../../integrations/chatops/slack.md), you can provide the user's Slack ID to give them the same permissions when interacting through Slack as they would have when interacting through the Spacelift website.
+
+## IdP group mapping
+
+Groups are reported by your Identity Provider for each user during authentication. You can add permissions to those groups that will be honored inside Spacelift. To do that, go to **IdP group mapping** tab and click **Map IdP group**. Then select the appropriate Spaces and Roles the same way you would for a single User.
+
+!!! warning
+ Group permissions will only be applied to the user if the group name in Spacelift exactly matches the group name in your Identity Provider including capital letters and whitespaces.
+
+### Slack integration
+
+After setting up the [Slack integration](../../integrations/chatops/slack.md) you can also grant permissions to entire Slack channels after selecting **Integrations** tab and clicking **Manage access** button in Slack card. You can input a human-readable name along the Slack channel ID. You can then add Space permissions the same way you would for Users and Groups.
diff --git a/docs/concepts/user-management/user.md b/docs/concepts/user-management/user.md
new file mode 100644
index 000000000..80e552699
--- /dev/null
+++ b/docs/concepts/user-management/user.md
@@ -0,0 +1,21 @@
+# User
+
+We consider **Users** to be all entities that can access Spacelift through the account's Identity Provider after going through the invitation flow, as described on the [User Management page](README.md).
+
+## Access settings
+
+Access settings can be found by clicking the button in the lower-left corner with your avatar and selecting **Personal settings**.
+
+## Requesting an invitation
+
+If a user wants another user to be invited, they can use **Collaborate with your team** banner, to request an invitation for a specified email address. This request will be delivered to account owners and admins to evaluate the request.
+
+## Spaces
+
+This page displays a list of spaces the user has access to, along with the role user has within that spaces. The list of roles and their descriptions can be found on the [User Management page](README.md).
+
+In addition to displaying existing permissions, the user can request a role change for a space they have access to, either directly or by inheritance, by clicking **Request role change** button to the left of desired space. You can read more about [Spaces](../spaces/README.md) and [Access Control](../spaces/access-control.md) in linked articles from this documentation.
+
+## Groups
+
+A list of Groups reported by the Identity Provider on the most recent login will be displayed in this list.
diff --git a/docs/getting-started.md b/docs/getting-started.md
index f46077169..eb3c44be3 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -153,11 +153,22 @@ Now it is time to add other users to your Spacelift account.
Now comes the moment when you want to show Spacelift to your colleagues. There are a few different ways to grant users access to your Spacelift account but in the beginning, we are going to add them as single users.
-Go to the "Policies" page that can be found on the left sidebar and click the "Create policy" button in the top-right corner.
+### User management
-
+Using [user management](concepts/user-management/README.md) is the simplest way to invite new users to Spacelift. You can follow the invitation process as described [here](concepts/user-management/README.md#invitation-process).
-Name the policy and select "Login policy" as the type.
+!!! note
+ It's important to know that all invites issued and access rules assigned won’t work until you [change user management strategy](concepts/user-management/README.md#migrating-from-login-policy) from login policy to user management.
+
+### Login policy
+
+Another way of adding users to Spacelift is using a login policy.
+
+Go to the "Organization settings" page that can be found in the user dropdown in the bottom of the left sidebar. Once there, choose "Login policy" from settings menu and click the "Create policy" button in the top-right corner.
+
+
+
+Name the policy and click "Continue" button.
Then copy/paste and edit the example below that matches the identity provider you used to sign up for the Spacelift account.
@@ -199,7 +210,7 @@ Now your colleagues should be able to access your Spacelift account as well!
!!! note
While the approach above is fine to get started and try Spacelift, granting access to individuals is less safe than granting access to teams and restricting access to account members. In the latter case, when they lose access to your organization, they automatically lose access to Spacelift while when whitelisting individuals and not restricting access to members only, you'll need to remember to explicitly remove them from your Spacelift Login policy, too.
- Before you go live in production with Spacelift, we recommend that you switch to using teams in [Login policies](./concepts/policy/login-policy.md) and consider configuring the [Single Sign-On (SSO) integration](./integrations/single-sign-on/README.md), if applicable.
+ Before you go live in production with Spacelift, we recommend that you switch to using teams in [Login policies](./concepts/policy/login-policy.md) or [User management](./concepts/user-management/admin.md#idp-group-mappingE.md), if applicable.
## Additional Reading
diff --git a/docs/integrations/api.md b/docs/integrations/api.md
index 83e1f03c5..7e113c1ce 100644
--- a/docs/integrations/api.md
+++ b/docs/integrations/api.md
@@ -92,36 +92,39 @@ There are currently three ways of obtaining this token:
### Spacelift API Key > Token
-Spacelift supports creating and managing machine users with programmatic access to the Spacelift GraphQL API. These "machine users" are called API Keys and can be created by Spacelift admins through the _Settings_ panel.
+Spacelift supports creating and managing machine users with programmatic access to the Spacelift GraphQL API. These "machine users" are called API Keys and can be created by Spacelift admins through the _Organization settings_ panel.
!!! note
API keys are **virtual** **users** and are billed like regular users, too. Thus, **each API key used** (exchanged for a token) during any given billing cycle counts against the total number of users.
Steps to create API key in the UI:
-Click on Settings in the bottom left corner of the UI
+Click on Organization settings inside user dropdown menu in the bottom left corner of the UI
- 
+ 
-Choose API Keys menu and click on Add new API key
+Choose API Keys menu and click on Create API key
- 
+ 
-The API key creation form will allow you to specify an arbitrary key name, along with the _Admin_ setting and the list of _teams_. If the key is given admin privileges, it has full access to the Spacelift API and won't be subject to [access policies](../concepts/policy/stack-access-policy.md).
+The API key creation form will allow you to specify an arbitrary key name, along with the _Space_ access rule setting and the list of _groups_. If the key is given root space access with admin role it have admin privileges, it has full access to the Spacelift API and won't be subject to [access policies](../concepts/policy/stack-access-policy.md).
-For non-administrative keys, you may want to add a **virtual** list of teams that the key should "belong to" so that existing access policies based on [GitHub teams](source-control/github.md#team-based-access) or [SAML assertions](single-sign-on/README.md#setting-up-the-integration) can work with your API keys just as they do with regular users.
+!!! warning
+ You can create different space access rules but they won't take effect until you switch to [user management](../concepts/user-management/README.md)
+
+For non-administrative keys, you may want to add a **virtual** list of groups that the key should "belong to" so that existing access policies based on [GitHub teams](source-control/github.md#team-based-access) or [SAML assertions](single-sign-on/README.md#setting-up-the-integration) can work with your API keys just as they do with regular users.
Without further ado, let's create a non-administrative API key with virtual membership in two teams: _Developers_ and _DevOps:_
- 
+ 
-Once you click the _Add Key_ button, the API Key will be generated and a file will be automatically downloaded. The file contains the API token in two forms - one to be used with our API, and the other one as a `.terraformrc` snippet to access your [private modules](../vendors/terraform/module-registry.md) outside of Spacelift:
+Once you click the _Create_ button, the API Key will be generated and a file will be automatically downloaded. The file contains the API token in two forms - one to be used with our API, and the other one as a `.terraformrc` snippet to access your [private modules](../vendors/terraform/module-registry.md) outside of Spacelift:
diff --git a/docs/integrations/chatops/slack.md b/docs/integrations/chatops/slack.md
index efdea4441..49ceba34e 100644
--- a/docs/integrations/chatops/slack.md
+++ b/docs/integrations/chatops/slack.md
@@ -14,25 +14,23 @@ Here are examples of messages the Spacelift application sends to Slack;
## Linking your Spacelift account to the Slack workspace
-As a Spacelift and Slack admin, you can link your Spacelift account to the Slack workspace by going to the _Slack_ section of the _Settings_ screen.
+As a Spacelift and Slack admin, you can link your Spacelift account to the Slack workspace by going to the _Integrations_ section of the _Organization settings_ screen.
-The integration is an OAuth2 exchange which installs Slack Spacelift app in your workspace.
+The Slack integration is an OAuth2 exchange which installs Slack Spacelift app in your workspace.
-Once you install the Spacelift app, the account-level integration is finished and the _Slack_ section of the _Settings_ screen informs you that the two are talking to one another:
+Once you install the Spacelift app, the account-level integration is finished and the _Slack_ of the _Integrations_ screen informs you that the two are talking to one another:
-
+
Installing the Slack app doesn't automatically cause Spacelift to flood your Slack channels with torrents of notifications. These are set up on a per-stack basis using [Slack commands](slack.md#available-commands) and the management uses the Slack interface.
Though before that happens, you need to allow requests coming from Slack to access Spacelift stacks.
-## Managing access to Stacks with policies
+## Managing access to Stacks
Our Slack integration allows users in the Slack workspace to interact with stacks by adding the ability
to change their run state or view changes that are planned or were applied.
-Similar to regular requests to our HTTP APIs, requests and actions coming from Slack are subject to the policy-based access validation. If you haven't had a chance to review the [policy](../../concepts/policy/README.md) and [Spaces](../../concepts/spaces/README.md) documentation yet, please do it now before proceeding any further - you're risking a chance of getting lost.
-
### Available actions
Currently, we allow:
@@ -40,7 +38,7 @@ Currently, we allow:
- Confirming and discarding tracked runs.
- Viewing planned and actual changes.
-Both of these actions require specific permissions to be configured using the login policy.
+Both of these actions require specific permissions to be configured using the login policy or granted via Slack manage access view.
Confirming or discarding runs requires _Write_ level permissions while viewing changes requires _Read_ level permissions. The documentation sections about policies below describe how to setup and manage these permissions.
!!! info
@@ -48,7 +46,7 @@ Confirming or discarding runs requires _Write_ level permissions while viewing c
### Login policy
-Using [login policies](../../concepts/policy/login-policy.md) is the preferred way to control access for the Slack integration. Using them you can control who can access stacks which are in a specific [Space](../../concepts/spaces/README.md).
+Using [login policies](../../concepts/policy/login-policy.md) is the first way to control access for the Slack integration. Using them you can control who can access stacks which are in a specific [Space](../../concepts/spaces/README.md).
They allow for granular space access control using the provided policy data such as slack workspace details, Slack team information and user which interacted with the message data. Using the Login policy you can define rules which
would allow to have _Read_ or _Write_ level permissions for certain actions.
@@ -143,6 +141,19 @@ space_write["Y"] {
}
```
+### Manage Slack access page
+
+Using the Manage Slack access page is another way to control access for the Slack integration. Using this method you can control who can access stacks which are in a specific [Space](../../concepts/spaces/README.md) and base that access on a specific Slack channel.
+
+!!! warning
+ It's important to know that all access rules assigned won’t work until you [change user management strategy](../../concepts/user-management/README.md#migrating-from-login-policy) from login policy to user management.
+
+To manage slack access as account admin you should go to _Organization Settings_ _Integrations_ section and click on _Manage access_ button on _Slack_ card.
+
+You can than add new access rule by clicking _Grant access_ button and filling out the form.
+
+
+
## Available slash commands
!!! warning
diff --git a/nav.yaml b/nav.yaml
index 3214fb15b..da81df7e2 100644
--- a/nav.yaml
+++ b/nav.yaml
@@ -54,6 +54,10 @@ nav:
- concepts/spaces/deleting-a-space.md
- concepts/spaces/structuring-your-spaces-tree.md
- concepts/spaces/migrating-out-of-the-legacy-space.md
+ - User Management:
+ - concepts/user-management/README.md
+ - concepts/user-management/admin.md
+ - concepts/user-management/user.md
- concepts/vcs-agent-pools.md
- 🛰️ Platforms:
- Terraform: