From 5a0700dc1020d2f1bb633dd97b71c370bbf54ed3 Mon Sep 17 00:00:00 2001
From: Stacey Salamon <stacey.salamon@aiven.io>
Date: Wed, 30 Oct 2024 13:32:19 +0100
Subject: [PATCH] change structure Create separate org and project sections
 with subsections for roles and permissions in each.

---
 docs/platform/concepts/permissions.md | 31 +++++++++++----------------
 1 file changed, 13 insertions(+), 18 deletions(-)

diff --git a/docs/platform/concepts/permissions.md b/docs/platform/concepts/permissions.md
index 81950a28..a0e14cf9 100644
--- a/docs/platform/concepts/permissions.md
+++ b/docs/platform/concepts/permissions.md
@@ -20,20 +20,20 @@ Permissions are not yet fully supported in the Aiven Console. They are intended
 use with the Aiven API, Aiven Provider for Terraform, and Aiven Operator for Kubernetes.
 :::
 
-## Organization roles
+## Organization roles and permissions
 
-You can grant the following roles to principals at the organization level. The permissions
-for each role apply to the organization and all units, projects, and services within it.
+You can grant the following roles and permissions to principals at the organization level.
+Roles and permissions at this level apply to the organization and all units, projects,
+and services within it.
+
+### Organization roles
 
 |    Console name     |          API name          |                                                                                                                                                                                                                                           Permissions                                                                                                                                                                                                                                           |
 | ------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Admin               | `role:organization:admin`  | <ul> <li> Full access to the organization. </li> <li> View and change billing information. </li> <li> Change the authentication policy. </li> <li> Invite, deactivate, and remove organization users. </li> <li> Create, edit, and delete groups. </li> <li> Create and delete application users and their tokens. </li> <li> Add and remove domains. </li> <li> Add, enable, disable, and remove identity providers. </li> </ul>                                                               |
-| Organization member | `role:organization:member` | Non-managed users can: <ul> <li> Edit their profiles. </li> <li> Create organizations. </li> <li> Leave organizations. </li> <li> Add [allowed authentication methods](/docs/platform/howto/set-authentication-policies). </li> <li> Generate and revoke personal tokens, if allowed by the [authentication policy](/docs/platform/howto/set-authentication-policies). </li> <li> Enable and disable feature previews. </li> </ul> This is the default role assigned to all organization users. |
-
-## Organization permissions
+| Organization member | `role:organization:member` | The default role assigned to all organization users. <br/> <br/> Non-managed users can: <ul> <li> Edit their profiles. </li> <li> Create organizations. </li> <li> Leave organizations. </li> <li> Add [allowed authentication methods](/docs/platform/howto/set-authentication-policies). </li> <li> Generate and revoke personal tokens, if allowed by the [authentication policy](/docs/platform/howto/set-authentication-policies). </li> <li> Enable and disable feature previews. </li> </ul> |
 
-You can grant the following permissions to principals. The actions listed for each
-permission apply to the organization and all units, projects, and services within it.
+### Organization permissions
 
 |          Console name           |             API name             |                                                                                                                                 Allowed actions                                                                                                                                 |
 | ------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -52,10 +52,11 @@ permission apply to the organization and all units, projects, and services withi
 | Manage projects                 | `organization:projects:write`    | <ul> <li> Create and delete projects. </li> <li> Change the billing group the project is assigned to. </li> <li> Move a project to another organization or unit. </li> <li> Add and remove project tags. </li> </ul> No access to other project settings or services. |
 
 
-## Project roles
+## Project roles and permissions
+You can grant the following permissions to principals. Roles and permissions granted at
+this level apply to the project and all services within it.
 
-You can grant the following roles for projects to principals. The permissions for each
-role apply to the project and all services within it.
+### Project roles
 
 | Console name |  API name   |                                                                                                                                                       Permissions                                                                                                                                                       |
 | ------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -64,13 +65,7 @@ role apply to the project and all services within it.
 | Operator     | `operator`  | <ul> <li> View project audit log. </li> <li> View project permissions. </li> <li>  Full access to all services in the project and their configuration. </li> </ul>                                                                                                                                                      |
 | Read only    | `read_only` | <ul> <li> View all services and their configuration. </li> </ul>                                                                                                                                                                                                                                                        |
 
-Project admin do not have access to organization settings such as billing unless
-they are also a [super admin](/docs/platform/howto/make-super-admin).
-
-## Project and service permissions
-
-You can grant the following permissions to principals. The actions listed for each
-permission apply to the project and all services within it.
+### Project permissions
 
 |       Console name        |          API name           |                                          Allowed actions                                          |
 | ------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------- |