Groups API
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.
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.
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 for more information.
Group Resource Instances, and Users: Organize your resource instances and users into groups, allowing for simplified ReBAC permissions for:
Users: Including users in User Groups 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.
Say we create a marketing group and assign a member
role to it, we then assign users to the Group via a member
role. The API then derives other roles based on this assignment (See example below)
- Resource Instances: Grouping resources in a Resource Group enables you to manage access control for multiple resources simultaneously, ensuring all included resources share the same permission configuration.
Following the previous example, we can create another group in our marketing 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 creates an automatic 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. 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:
Let’s dive deeper into a simple use-case example for User Groups:
Say our company has several teams, each with a few employees assigned to each team. Our goal is to allow all members of the Marketing Team to Edit Social Media resources based on their group membership.
For this purpose, we will first create a group named teams
. The group, teams
is a resource, while each specific team (Such as marketing-team
) is a resource instance.
Users are assigned to the marketing-team
via the member
role (The member
role here is, of course, just an example. Feel free to customize roles as you wish).
As mentioned above, we also have a social_media
resource, and a training_video
- which is a resource instance of the social_media
type. This resource instance supports the role editor
.
Let’s set this up:
API Calls: Create Group, Add Role to Group, Add Users to Group:
To create a new group, make a POST request with the following data:
curl 'https://api.permit.io/v2/schema/{project_id}/{env_id}/groups' \
-H 'authorization: Bearer API_SECRET_KEY' \
--data-raw '{"group_instance_key": "marketing", "group_resource_type_key": "teams", "group_tenant": "default"}'
Create the social_media
resource:
curl 'https://api.permit.io/v2/schema/{proj_id}/{env_id}/resources' \
-H 'authorization: Bearer API_SECRET_KEY' \
--data-raw '{"key": "social_media", "name": "social media", "actions":{}}'
Create a training_video
resource instance:
curl 'https://api.permit.io/v2/schema/{proj_id}/{env_id}/resource_instances' \
-H 'authorization: Bearer API_SECRET_KEY' \
--data-raw '{"key": "training_video", "tenant": "business", "resource":"social_media"}'
Create a role called editor
curl 'https://api.permit.io/v2/schema/{proj_id}/{env_id}/roles' \
-H 'authorization: Bearer API_SECRET_KEY' \
--data-raw '{"key": "editor", "name”: "editor"}'
Next, we assign the editor
role to the marketing-team
group instance:
curl 'https://api.permit.io/v2/schema/{project_id}/{env_id}/group/{group_resource_type_key}/roles' \
-H 'authorization: Bearer API_SECRET_KEY' \
--data-raw '{"resource": "social_media", "resource_instance": "training_video", "role": "editor", tenant:"business"}'
Finally, assign a user to the marketing-team
group instance:
To add users to a group, make a PUT request with the following data:
curl -X PUT \
'https://api.permit.io/v2/schema/{project_id}/{env_id}/groups/{group_resource_type_key}/users/{user_id}' \
-H 'authorization: Bearer API_SECRET_KEY' \
--data-raw '{"tenant":"business"}'
Automated Role Derivation:
Once we assign the editor
role to marketing-team
group instance, the following will be automated by the API:
A role derivation will be created from team#member
to social_media#editor
A relation will be created between the teams
group and the social_media
resource. The name of this relation will be team_group
.
A relationship will be created between teams#marketing-team
and social_media#training_video
.
If a new user is assigned the member role on the marketing-team
resource, they will automatically be assigned the editor role on the social_media#training_video
instance.
Thus, every new marketing-team
member will be able to edit the social_media#training_video
resource instance.
Example Usage for Resource Groups
Let’s dive deeper into a simple use-case example for Resource Groups:
Say we have a Group and inside the group, we have the Support team and Organization 1. Our goal is to allow all members of the Support Team to be members in Organization 1 and in all of his related instances.
For this purpose, we will first create a group named Group
. The group, group
is a resource, while each specific group inside (Such as support-team
) is a resource instance.
Users are assigned to the support-team
via the member
role.
As mentioned above, we also have an Org1
resource instance.
This resource instance supports the role of member
.
Let’s set this up:
API Calls: Create Group, Add Role to Group, Add Group to Group:
To create a new group with Group instance support
, make a POST request with the following data:
curl 'https://api.permit.io/v2/schema/{project_id}/{env_id}/groups' \
-H 'authorization: Bearer API_SECRET_KEY' \
--data-raw '{"group_instance_key": "support", "group_tenant": "default"}'
Create another Group instance org1
:
curl 'https://api.permit.io/v2/schema/{project_id}/{env_id}/groups' \
-H 'authorization: Bearer API_SECRET_KEY' \
--data-raw '{"group_instance_key": "org1", "group_tenant": "default"}'
Now, we want to create a connection between those two group instances.
curl -X PUT \
'https://api.permit.io/v2/schema/{project_id}/{env_id}/groups/{group_instance_key}/assign_group' \
-H 'authorization: Bearer API_SECRET_KEY' \
--data-raw '{"group_instance_key": "org1"}'
Once we assign the org1
group instance to the support
group instance, the following will be automated by the API:
- A role derivation will be created from group#member' to
group#member
- A relation will be created between the
group
resource and thegroup
resource. The name of this relation will begroup
. - A relationship will be created between
group#support-team
andgroup#org1
.