organization users

modules/ROOT/pages/user-management.adoc

@@ -5,18 +5,22 @@
 
 User management is a feature within Aura that allows admins to invite users and set their roles within an isolated environment.
 
+You can view and manage roles from *Users* pages, accessible via the console sidebar.
+An organization has one *Users* page for managing organization-level roles.
+Each project has a *Users* page for managing project-specific roles.
+
 [NOTE]
 ====
-To invite users, you must perform the action at the project level.
-Go to *Project > Users* to send an invitation.
-When you invite someone at the project level, they are automatically added to the organization as an `ORG_MEMBER`.
-After the user accepts the invite, you can optionally update their organization-level role via *Organization > Users*.
-However, editing an organization role is not required unless you want to grant them specific organization-wide permissions.
+Users can only be invited on the project-level. 
+Regardless of which project-role is specified in the invitation, the user is added to the organization as an `ORG_MEMBER` by default. 
+The organization-level role cannot be changed until the user accepts their invitation.
 ====
 
 == Organization-level roles
 
-The following roles are available at the org level and these are assigned via invitation:
+Roles at the organization level determine what administrative capabilities a user has across all projects within the organization.
+
+The following roles are available at the org level:
 
 * Owner
 * Admin
@@ -137,27 +141,8 @@ The following roles are available at the org level and these are assigned via in
 |
 |===
 
-== Project-level roles
-
-The project you're currently viewing is displayed in the header of the console.
-You can select the project name to open the project dropdown menu, allowing you to view all the projects that you have access to and switch between them.
-
-Additionally, you can perform the following actions from the *Project Settings* page.
-You can access the **Settings** page by selecting **Settings** from the sidebar menu of the console.
-
-* Edit the name of the project you are currently viewing by selecting the pencil icon next to the project name. This action requires you to be an Admin of the project.
-
-* Copy the Project ID by selecting the clipboard icon that appears next to the Project ID.
-
-== Users
-
-Each project can have multiple users with individual accounts allowing access to the same environment.
-
-The users with access to a project can be viewed and managed from the **Users** page.
-You can access the **Users** page by selecting **Users** from the sidebar menu of the console.
-
 [[roles]]
-=== Roles
+== Project-level roles
 
 Users within a project can be assigned one of the following roles:
 
@@ -166,7 +151,12 @@ Users within a project can be assigned one of the following roles:
 * _Project Member_
 * _Project Admin_
 
-==== Metrics reader role
+[NOTE]
+====
+Each project must have at least one Project Admin, but it is also possible for projects to have multiple Project Admins.
+====
+
+=== Metrics reader role
 
 The `metrics reader` role can be assigned to any user or service account.
 It has the same permissions as the `project viewer` role, but with some extra permissions specifically for reading metrics via an API endpoint.
@@ -175,11 +165,6 @@ Accessing metric endpoints requires xref:/api/authentication.adoc[Aura API Crede
 
 The `metrics reader` role can view and open instances in the console, however, login to the instance is required to interact with it, with access to Explore and Query defined by the instance’s RBAC settings.
 
-[NOTE]
-====
-Each project must have at least one Project Admin, but it is also possible for projects to have multiple Project Admins.
-====
-
 :check-mark: icon:check[]
 
 .Roles and console capabilities
@@ -264,7 +249,6 @@ Each project must have at least one Project Admin, but it is also possible for p
 | {check-mark}
 |===
 
-
 === Predefined roles
 
 Users within a project can access instances seamlessly with their console role if xref:security/tool-auth.adoc[Tool authentication with Aura user] is enabled.
@@ -448,54 +432,29 @@ The predefined roles are assigned the following privileges on the instance level
 | {check-mark}
 |===
 
-
-=== Inviting users
-
-As an _Admin_, to invite a new user:
-
-. Within a project, go to *Users* and select *Invite user*.
-. Enter the **Email** address of the person you want to invite.
-. Select the user's **Role**.
-. Select **Invite**.
-
-The new user will appear within the list of users on the **User** page with the _Pending invite_ **Status** until they accept the invite.
-
-An email will be sent to the user with a link to accept the invite.
-
-.Grant users access to a project
-image::inviteusers.png[]
-
-=== Editing users
-
-As an _Admin_, to edit an existing user's role:
-
-. Select the more actions (three dots) icon next to the user's name from the **User** page.
-. Select the user's new **Role**.
-. Select **Save**.
-
-=== Deleting users
-
-As an _Admin_, to delete an existing user:
-
-. Select the more actions (three dots) next to the user's name from the **User** page.
-. Select **Delete**.
-
 // [NOTE]
 // ====
 // It is also possible to delete a user whose **Status** is _Pending invite_.
 
 // Select the trash can icon next to the user's name, and then select **Revoke**.
 // ====
 
-=== Accepting an invite
-
-When invited to a project, you will receive an email with a link to accept the invite.
-This link will direct you to the Aura console, where a **Project invitation** modal will appear.
-You can select the project(s) you have been invited to and choose to accept or decline the invite(s).
-
-// You can also close the **Project invitation** modal without accepting or declining the invite(s) and later manually re-open the modal by selecting the **Pending invites** envelope icon in the console header.
-
 // [TIP]
 // ====
 // User management within the Aura console does not replace built-in roles or fine-grained RBAC at the database level.
 // ====
+
+=== Invite users
+
+* As an _Admin_, go to *Users* from within a project, and select *Invite users*.
+You need to provide an email address for the new user and decide which project-level role to assign them. 
+* The invited user will receive an email with a link to accept the invitation and their status is *Pending* until they accept the invitation.
+Note that on accepting the invite, the invited user automatically gets an `ORG_MEMBER` role in the organization the project is part of.
+If needed, you can edit the organization-level role after the invite is accepted.
+
+.Grant users access to a project
+image::inviteusers.png[]
+
+=== Edit users and roles
+
+From the *Users* page, as and _Admin_, you can delete users or edit their roles using the [...] more menu by the user's name.