New Groups API version for review

docs/api/rebac/groups.mdx

@@ -6,60 +6,86 @@ title: Groups API
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-The Groups API allows you to manage your resources and users within groups. You can create, update, delete, and list groups.
-Groups enable you to easily group together resources, resource-instances, and users. In addition groups simplify ReBAC permissions for users, by allowing roles to be assigned to the groups themselves.
-You can assign roles to a group and then add users to the group through the Groups API.
-The users within the group will derive roles form the roles assigned to the group .
+The Groups API simplifies permission management for your resources and users by using groups. Groups can include resources, resource instances, and users, enabling you to set permissions for everything contained within a group at once.
+
+## Key Features:
+
+- **Create, Update, Delete, and List Groups:** The Groups API provides a comprehensive set of endpoints to manage the lifecycle of your groups, ensuring you have complete control over their configuration and membership.
+- **User Membership:** When adding users to the group through the API, you can set them to automatically derive their permissions from the roles assigned to the group, ensuring consistent and manageable access control. See the [Groups Redoc](https://www.notion.so/) for more information.
+- **Group Resources, Resource Instances, and Users:** Organize your resources and users into groups, allowing for simplified ReBAC permissions for:
+
+    - **Users:** Creating a group of users allows you to assign an entire cluster of users with a single role (Instead of assigning roles to each user individually). You can set a role assigned to the group to be automatically assigned to all its members and revoked once their membership is removed. 
+
+    :::info Example:
+    If we create a `marketing` group and assign a `marketing-team-member` role to it, we can give an entire group of users access to a shared marketing resource.
+    :::
+
+    - **Resources:** Grouping resources enables you to manage access control for multiple resources simultaneously, ensuring all included resources share the same permission configuration.
+
+    :::info Example:
+    If we create a `marketing-resources` group, we can assign a role to a user (Or group of users!) that gives them permission to perform certain actions on all resources within the `marketing-resources` group.
+    :::
+
+    - **Resource Instances:** Grouping resource instances allows you to manage permissions for a group of specific resource instances collectively. As with resource groups, this ensures all resource instances within the group share the same permission configuration.
+
+    :::info Example: 
+    If we create a `social-media-campaigns` group and populate it with the instances of our social media campaigns (`campaign-1`, `campaign-2`), we can assign a user (Or group of users) a role that gives them access to perform specific actions on this group of resource instances. 
+    :::
+
 
-Check the [Groups Redoc ](/) for more information.
+## Example Usage for User Groups
 
+Let's say we want to assign a group of users, the "Marketing Team," access to a group of social media resources. 
 
-## Example Usage for User Groups
+- Using the Groups API, we'll first create a group named `marketing-team`.
+- Next, we will assign users to the `marketing-team` group.
+- The group will be assigned a `member` role.
 
-### Assign roles to a group:
+- Additionally, we will have a resource group called `social-media` .
+- Next, we will assign resources to the `social-media` group.
+- The `social-media` group will support the role `viewer`.
 
-Let's say we want to represent a company and its employees as a group, and then assign all the employees access to a shared marketing resource (social-media) via the group.  We'll have a group named 'company' (Which is represented as a resource named 'company'), and an instance of a specific company 'Acme'.  Users are assigned to `Acme` via a role called `member`
-Additionally, we will have a resource-instance of type 'marketing' - 'social_media' which supports the role 'editor'.
-Once we assign the role 'editor' to  the `company` group, the following will by automated by API:
-- create role derivation from 'company#member' to 'marketing#editor'
-- create a relation between 'company' and 'marketing' with a relation between 'company_group'
-- create relationship between 'company#Acme' and 'marketing#social_media'.
+Once we assign the `viewer` role to the `marketing-team` group, the following will be automated by the API: 
 
-![](groups-diagram.png)
+- Create a role derivation from `marketing-team#member` to `social-media#viewer`.
+- Establish a relation between `marketing-team` and `social-media` .
+- Create a relationship between `marketing-team` and each resource within the `social-media` group.
 
-Then we will have group 'company' and every user who is a 'member' in this group will have the role 'editor' in the resource 'marketing#social_media'.
+After these steps, we will have the `marketing-team` group, and every user who is a `member` in this group will have the role `viewer` in all resources within the `social-media` group. 
 
-### Assign users to a group:
+### Assign Users to a Group
 
-When you assign "user-1" to 'company' group, the following will by automated by API:
-- assign 'user-1' to 'company#member' role
+When you assign `user-1` to the `marketing-team` group, the following will be automated by the API:
 
-and the user will also get the role 'marketing#editor' in the resource 'marketing#social_media'.
+- Assign `user-1` to the `marketing-team#member` role.
+- Grant `user-1` the role `social-media#viewer` in all resources within the `social-media` group.
 
+Using the Groups API, you can efficiently manage permissions and ensure that all members of the `marketing team` have the appropriate access to the `social media` resources group.
 
 ## Create a Group via API
 
 To create a new group, make a POST request to the following with the required data:
 
 ```bash
-curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/groups' \
+curl '<https://api.permit.io/v2/facts/{project_id}/{env_id}/groups>' \\
   -H 'authorization: Bearer API_SECRET_KEY'
-  --data-raw '{"group_instance_key": "Acme"}' \
+  --data-raw '{"group_instance_key": "marketing-team"}' \\
 ```
 
 To add a new role to group, make a POST request to the following with the required data:
 
 ```bash
-curl 'https://api.permit.io/v2/facts/{project_id}/{env_id}/group/{group_resource_type_key}/roles' \
+curl '<https://api.permit.io/v2/facts/{project_id}/{env_id}/group/{group_resource_type_key}/roles>' \\
   -H 'authorization: Bearer API_SECRET_KEY'
-  --data-raw '{"resource": "marketing", "resource_instance": "social_media", "role": "editor", tenant:"business"}' \
+  --data-raw '{"resource": "marketing", "resource_instance": "social_media", "role": "viewer", tenant:"business"}' \\
+
 ```
 
 To add users to a group, make a PUT request to the following with the required data:
 
-```bash
-curl -X PUT \
-'https://api.permit.io/v2/facts/{project_id}/{env_id}/groups/{group_resource_type_key}/users/{user_id}' \
+```
+curl -X PUT \\
+'<https://api.permit.io/v2/facts/{project_id}/{env_id}/groups/{group_resource_type_key}/users/{user_id}>' \\
     -H 'authorization
-      --data-raw '{"tenant":"business"}' \
-    ```
+      --data-raw '{"tenant":"business"}' \\
+```