diff --git a/docs/platform/concepts/managed-users.md b/docs/platform/concepts/managed-users.md
index d8062194..c4a943d1 100644
--- a/docs/platform/concepts/managed-users.md
+++ b/docs/platform/concepts/managed-users.md
@@ -4,10 +4,19 @@ title: Managed users
import ConsoleLabel from "@site/src/components/ConsoleIcons"
-The managed users feature lets you centrally manage your organization's users, including editing their profiles and resetting passwords.
+The managed users feature lets you centrally manage your organization's users and helps you to secure your organization in Aiven.
-A managed user cannot create new organizations
-unless they are a [super admin](/docs/platform/howto/make-super-admin) of the organization.
+With managed users, you can:
+
+- Control how users log in with [authentication policies](/docs/platform/howto/set-authentication-policies),
+ not just how they access the organization
+- Have visibility of all users in your domain even if they weren't added to the Aiven
+ organization
+- Set their state, including deactivating and deleting user accounts
+
+Managed users are also restricted from making changes to their profiles and creating new
+organizations. Only [super admin](/docs/platform/howto/make-super-admin)
+can create organizations.
## Make organizations user managed users
@@ -22,6 +31,6 @@ Users in an organization with a verified domain automatically become managed use
1. Click **Admin**.
1. Select **Users**.
-1. Next to the user to deactivate, click > **Deactivate**.
+1. Find the user and click > **Deactivate**.
You can follow the same process to reactivate the user.
diff --git a/docs/platform/howto/manage-domains.md b/docs/platform/howto/manage-domains.md
index 95b21ff5..44f97208 100644
--- a/docs/platform/howto/manage-domains.md
+++ b/docs/platform/howto/manage-domains.md
@@ -4,19 +4,18 @@ title: Manage domains
import ConsoleLabel from "@site/src/components/ConsoleIcons"
-Verified domains let you manage users in your organization.
+Adding a verified domain in Aiven adds an extra layer of security to managing your organization's users. When you verify a domain, your organization users automatically become
+[managed users](/docs/platform/concepts/managed-users).
+
There are two ways you can verify a domain:
- by adding a DNS TXT record to the domain (recommended)
- by uploading an HTML file to your website
-After adding a domain, organization users automatically become
-[managed users](/docs/platform/concepts/managed-users).
-
## Add a domain using a DNS TXT record
-1. In the organization where to add a domain to, click **Admin**.
+1. In the organization, click **Admin**.
1. Click **Domains**.
@@ -55,8 +54,7 @@ can retry it by repeating the last step.
## Add a domain using an HTML file
-1. In the organization where to add a domain to, click
- **Admin**.
+1. In the organization, click **Admin**.
1. Click **Domains**.
1. Click **Add domain**.
1. Enter a **Domain name**.
@@ -74,7 +72,6 @@ can retry it by repeating the last step.
Removing a domain is an irreversible action.
:::
-1. In the organization to remove a domain from, click
- **Admin**.
+1. In the organization, click **Admin**.
1. Click **Domains**.
-1. Find the domain to remove and click > **Remove** and confirm.
+1. Find the domain and click > **Remove**.
diff --git a/docs/platform/howto/set-authentication-policies.md b/docs/platform/howto/set-authentication-policies.md
index b8b103ef..baa40a0a 100644
--- a/docs/platform/howto/set-authentication-policies.md
+++ b/docs/platform/howto/set-authentication-policies.md
@@ -2,13 +2,14 @@
title: Set authentication policies for organization users
---
-The authentication policy for your organization specifies the ways that
-users can access your organization on the Aiven platform: with a
-password, third-party authentication, or organization single sign-on
-(SSO).
+The authentication policy for your organization specifies the ways that users in your organization and their personal tokens can access the organization on the Aiven platform.
## Authentication types
+When creating an authentication policy, you select the authentication methods to allow
+for all users in your organization. For increased security, it's a good idea to always
+[verify your organization's domains](/docs/platform/howto/manage-domains).
+
### Passwords and two-factor authentication
With password authentication enabled, users log in with their email
@@ -16,30 +17,60 @@ address and password. For an added layer of security, you can enforce
two-factor authentication (2FA) for password logins for all users in
your organization.
-When 2FA is required, users won't be able to
-access any resources in your organization until they set up 2FA.
+When 2FA is required, users can't access any resources in your organization until they
+set up 2FA.
:::note
-Authentication tokens are not affected and continue to work when you make 2FA required.
-However, when users [enable 2FA](/docs/platform/howto/user-2fa) their existing authentication tokens are revoked.
+Personal tokens are not affected and continue to work when you make 2FA required.
+However, when users [enable 2FA](/docs/platform/howto/user-2fa) their existing tokens
+might stop working.
:::
### Third-party authentication
Users can choose to log in using Google, Microsoft, or GitHub.
-### Organization identity providers (SSO)
+### SSO with an organization identity provider
+
+Users that are part of multiple Aiven organizations can log in using single sign-on (SSO)
+and access your organization’s resources with an
+[identity provider](/docs/platform/howto/saml/add-identity-providers) that is configured
+for any of those organizations.
+
+You can further restrict access by requiring users to log in with one of your
+organization’s identity providers. This means that they cannot
+log in to your organization using another Aiven organization's identity provider. It's
+strongly recommended to enable this if you only have one Aiven organization.
+
+### Personal tokens
+
+Users can generate their own
+[personal tokens](/docs/platform/howto/create_authentication_token) for use with
+the Aiven API. When you turn off personal tokens, managed users can't create
+personal tokens. Non-managed users can still create personal tokens, but they can't use
+them to access the organization's resources.
+
+To regularly manage your resources programmatically with the API, CLI, Terraform,
+or other applications, it's best to create an [application user](/docs/platform/howto/manage-application-users) with its own tokens.
+
+Personal tokens are generated with the authentication method that the user logged in with.
+Tokens are linked to the authentication method they are created with. You can ensure that
+access to your organization using tokens conforms to the authentication policy by
+requiring users to be logged in with an allowed authentication method when they
+use a token. If your authentication policy changes, tokens that don’t conform to the
+new policy stop working.
-Organization users are restricted to logging in using SSO through an
-[identity provider](/docs/platform/howto/saml/add-identity-providers).
+For example, if you have an authentication policy that allows users to log in with a
+password, a user can log in with their email and password, and create a personal token.
+This token is tied to the password authentication method they logged in with.
+If the authentication policy changes later to only allow logging on with an identity
+provider, then the token generated when the user was logged in with their password will
+not work. After logging in with an allowed method on the new authentication policy
+the user can create a new token.
## Set an authentication policy
-To set an authentication policy for all users in an organization:
-
1. In the organization, click **Admin**.
1. Click **Authentication**.
-1. Click the toggle for each authentication method to
- allow.
+1. Configure the settings for your authentication policy.
1. Click **Save changes**.
-