Groups API

The Groups API simplifies relationship-based permission management for your resource instances and users by using groups. Groups, as suggests the name, group together resource instances and users, enabling you to assign group members with permissions on resource instances.

Performance-Optimized Endpoints

The Groups API has been updated with new, performance-optimized endpoints. See the Additional API Operations section for the latest recommended methods. Previous GET endpoints are considered deprecated in favor of these improved alternatives. They should not be used and will be removed in the future.

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) is a resource instance.

Users are assigned to the marketing 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 group instance: Note: group_instance_key is formatted as type:instance

curl 'https://api.permit.io/v2/schema/{project_id}/{env_id}/group/teams:marketing/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 teams:marketing 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 teams:marketing 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 and social_media#training_video. If a new user is assigned the member role on the marketing resource, they will automatically be assigned the editor role on the social_media#training_video instance. Thus, every new marketing 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": "group: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.

Assign Group to Group

Current behavior:

The "Assign Group to Group" functionality currently supports only groups that belong to the same resource type.

Extended support for this function may be added in the future to allow assignment between groups with different resource types.

Additional API Operations

The Groups API provides several improved endpoints for querying and managing group relationships, memberships, and permissions. These operations allow you to retrieve detailed information about your groups with enhanced performance.

Performance Improvements

The endpoints documented below are new and improved versions that offer better performance compared to the previous API methods. The older GET endpoints have been deprecated in favor of these optimized alternatives.

List All Groups

To retrieve all groups (without nested relationships), make a GET request:

curl -X GET \
'https://api.permit.io/v2/schema/{proj_id}/{env_id}/groups/direct' \
  -H 'authorization: Bearer API_SECRET_KEY'

This endpoint returns a flat list of all groups without their hierarchical relationships, useful for getting a quick overview of all groups in your environment. This is the recommended method for listing groups with improved performance.

Get a Specific Group

To retrieve details of a specific group, make a GET request with the group instance key:

curl -X GET \
'https://api.permit.io/v2/schema/{proj_id}/{env_id}/groups/direct/{group_instance_key}' \
  -H 'authorization: Bearer API_SECRET_KEY'

This returns detailed information about the marketing group, including its configuration and metadata.

Get Group Children

To retrieve all child groups of a specific group, make a GET request:

curl -X GET \
'https://api.permit.io/v2/schema/{proj_id}/{env_id}/groups/{group_instance_key}/children' \
  -H 'authorization: Bearer API_SECRET_KEY'

This endpoint returns all groups that are children of the marketing group, helping you understand the hierarchical structure. For example, if marketing has child groups like content-team and design-team, they will be listed here.

Get Group Parents

To retrieve all parent groups of a specific group, make a GET request:

curl -X GET \
'https://api.permit.io/v2/schema/{proj_id}/{env_id}/groups/{group_instance_key}/parents' \
  -H 'authorization: Bearer API_SECRET_KEY'

This endpoint returns all groups that are parents of the content-team group, allowing you to trace the group hierarchy upward.

Get Group Users

To retrieve all users assigned to a specific group, make a GET request:

curl -X GET \
'https://api.permit.io/v2/schema/{proj_id}/{env_id}/groups/{group_instance_key}/users' \
  -H 'authorization: Bearer API_SECRET_KEY'

This endpoint returns all users that are members of the marketing group, including their user details and assigned roles within the group.

Get Group Roles

To retrieve all roles assigned to a specific group, make a GET request:

curl -X GET \
'https://api.permit.io/v2/schema/{proj_id}/{env_id}/groups/{group_instance_key}/roles' \
  -H 'authorization: Bearer API_SECRET_KEY'

This endpoint returns all role assignments for the marketing group, showing which roles the group has on various resource instances.

API Reference

For complete API documentation including request/response schemas, query parameters, and additional endpoints, visit the Groups API Reference.

Key Features:​

Example Usage for User Groups:​

API Calls: Create Group, Add Role to Group, Add Users to Group:​

Automated Role Derivation:​

Example Usage for Resource Groups​

API Calls: Create Group, Add Role to Group, Add Group to Group:​

Assign Group to Group​

Additional API Operations​

List All Groups​

Get a Specific Group​

Get Group Children​

Get Group Parents​

Get Group Users​

Get Group Roles​

API Reference​

Contents