New Groups API version for review #372
Conversation
✅ Deploy Preview for permitio-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
docs/api/rebac/groups.mdx
Outdated
| ## 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. |
There was a problem hiding this comment.
There was a problem hiding this comment.
Please don't have "Upcoming feature" in the URL- that means the URL will break once that changes.
Use admonitions in the text instead
There was a problem hiding this comment.
@maya-barak please fix the link before I push changes.
docs/api/rebac/groups.mdx
Outdated
| - **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. |
There was a problem hiding this comment.
the 'marketing-team-member' role and 'marketing-resources' are not expressions that fit for what we wanted for this example, @orweis - your opinion?
There was a problem hiding this comment.
Let's switch the resource to be (an external) document
docs/api/rebac/groups.mdx
Outdated
| 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. |
There was a problem hiding this comment.
"Groups can include resources, resource instances..." - you can group resource types to set up the scheme of your app resources, later the permission will be managed on resource instances groups according the the scheme that was set on the type. so when saying "Groups can include resources, resource instances and users..." I think it communicates the wrong idea.
" enabling you to set permissions for everything contained within a group at once" - only relevant for user groups. I think it's confusing in the context of resource groups.
There was a problem hiding this comment.
For the first note: I agree. Changed to: "These can be used to group together resources, resource instances, or users,"
As for the second note, how's: "enabling you to set a unified permission scheme for everything contained within a group"? I need something that works for all three group types..
docs/api/rebac/groups.mdx
Outdated
| 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. |
There was a problem hiding this comment.
continuing the comment from above, I think there is some misunderstanding around the resource group use case, would love to chat about this more
| - **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: |
| :::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. | ||
| ::: |
There was a problem hiding this comment.
You're confusing giving an example of usage, and what would be created behind the scenes
The groups API doesn't "allows you to create a derivation" it does so for us automatically
| :::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. | ||
| ::: |
There was a problem hiding this comment.
This is not a new example - it's part of the previous one.
Not sure this needs to be an admonition at all
Co-authored-by: Or Weis <[email protected]>
Still missing diagram.
Might have some mistakes and require fixing the API code.
Please review.