Skip to main content
Version: 2.0.0

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.

How it Works:

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.
How it Works:

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/facts/{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/facts/{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/facts/{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/facts/{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/facts/{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/facts/{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/facts/{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 the group resource. The name of this relation will be group.
  • A relationship will be created between group#support-team and group#org1.

Contents