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 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.

      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.

      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.

      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:​

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.

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.

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:

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:

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"}' \\

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"}' \\

Automated Role Derivation:​

Groups API

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.

Contents