New Groups API version for review

docs/api/rebac/groups.mdx

@@ -6,60 +6,93 @@ 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 relationship-based permission management for your resource instances and users by using groups. Groups, as suggested by the name, group together resource instances and users, enabling you to assign group members with permissions on resource instances.
 
-Check the [Groups Redoc ](/) for more information.
+## 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.
 
-## Example Usage for User Groups
 
-### Assign roles to a group:
+- **Assigning roles to Groups**: Groups can be assigned roles directly (instead of users). When adding users to a group through the API, you set them to automatically derive their permissions from the roles assigned to the group, 
+ensuring consistent and manageable access control. See the [Groups API Redoc](https://api.permit.io/v2/redoc#tag/Groups-(Upcoming-Feature)) for more information.
 
-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'.
 
-![](groups-diagram.png)
+- **Group Resource Instances, and Users**: Organize your resource instances and users into groups, allowing for simplified ReBAC permissions for:
 
-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'.
+    - **Users:** Users: Including users in a group 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 `member` role to it, we then assign users to the Group via the `member` role. We can then derive other roles based on this assignment (See example below)
+    :::
+
+    - **Resource Instances**: Grouping resources enables you to manage access control for multiple resources simultaneously, ensuring all included resources share the same permission configuration.
 
-### Assign users to a group:
+    :::info Example:
+    In our marketing group, we can create another group titled `social_media`. This group will contain resource instances of marketing materials. We can assign this newly created group the role of editor. 
+    The Groups API allows you to create a derivation between the `social_media#editor` role and the `marketing#member` role - meaning all users with the `marketing#member` role will automatically be assigned 
+    with the `social_media#editor` role.
+    :::
+    :::info Example:
+    New resources added to `social_media` will be accessible to edit by members of the marketing group, and new users added as members to the marketing group will automatically 
+    have editor access to social media assets.
+    :::
+
+## Example Usage for User Groups:
 
-When you assign "user-1" to 'company' group, the following will by automated by API:
-- assign 'user-1' to 'company#member' role
+Let's get into the previous example with more detail:
+Say we want to assign a group of users, the "Marketing Team," "Editor" access to a group of social media resources. We also want them to have "Viewer" access to an external "Training Video" resource.
 
-and the user will also get the role 'marketing#editor' in the resource 'marketing#social_media'.
+### Group creation and role assignment:
+- Using the Groups API, we'll first create a group named `marketing`.
+- Next, we assign the group three roles: `editor`, `viewer`, and `member`.
+- Then, we create another group called `social_media` . This group has one role: `content`.
 
+### Setting Up Relationships:
+- We assign our users with the `marketing#member` role.
+- We assign the `social_media` group with the `content` role.
+- We assign `social media` resource instances (`meme_1`, `video_2`, `calendar_3`) the `social-media#content` role.
+- Last, we set our external resource - `training_video` to support the `marketing#viewer` role.
 
-## Create a Group via API
+#### API Calls: Create Group, Add Role to Group, Add Users to Group:
+To **create a new group**, make a POST request to the following with the required data:
 
-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' \
-  -H 'authorization: Bearer API_SECRET_KEY'
-  --data-raw '{"group_instance_key": "Acme"}' \
+```
+curl '<https://api.permit.io/v2/facts/{project_id}/{env_id}/groups>' \\
+ -H 'authorization: Bearer API_SECRET_KEY'
+ --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:
+To **add a new role to group**, make a POST request to the following with the required data:
+```
+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": "viewer", tenant:"business"}' \\
+```
 
-```bash
-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"}' \
+#### Assigning Users to a Group
+To **add users to a group**, make a PUT request to the following with the required data:
+```
+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"}' \\
 ```
 
-To add users to a group, make a PUT request to the following with the required data:
+### Automated Role Derivation:
+
+![Groups API](/ui-videos/api/rebac/groups-api/docsapi.png)
+
+Once `user-1` is assigned to the marketing group, the following will be automated by the API:
+
+- Assign `user-1` to the `marketing#member` role.
+- Create a role derivation from `marketing#member` to `social_media#editor`.
+- Create a role derivation from `marketing#member` to `training_video#viewer`.
+- Create a role derivation from `social_media#editor` to `social-media#content`.
+- Establish a relation between `marketing` and `social-media`.
+- Create a relationship between `marketing` and each resource within the `social-media` group.
+- Grant `user-1` the role `social_media#editor` in all resources within the `social_media` group.
+- Grant `user-1` the role `marketing#viewer`, granting `view` access to the `training_video` instance. 
+
+After these steps, we will have the marketing group, and every user who is a member in this group will have the role editor in all resources within the social-media group, and the role viewer on training_video. 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.
 
-```bash
-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"}' \
-    ```