Groups API

Use the Permit.io Groups API to give a set of users the same access in one call: assign a role to a group, and every member of the group derives that role. This page is for developers who manage relationship-based access control (ReBAC) groups through the API. To manage groups in the Permit dashboard instead, see Groups UI.

How groups work

A group is a resource instance of a group resource type, in one tenant. For example, the marketing instance of the teams resource type is a group. Groups build on ReBAC role derivation:

• Group members. When you add a user to a group, Permit assigns the user the member role on the group instance. When you remove the user, Permit removes that role, and the user stops deriving the group's roles.
• Group roles. When you assign a role on a resource instance to a group, Permit creates three objects: a relation between the group resource type and the resource type, a relationship between the group instance and the resource instance, and a role derivation from the group's member role to the assigned role. Every member of the group derives the assigned role on the resource instance, including users you add later.
• Group hierarchy. When you assign one group to another group, Permit links the two groups with a relationship and a derivation between their member roles. Group-to-group assignment works only between groups of the same resource type.

Example: a marketing team that edits a training video

The marketing team must edit the training_video instance of the social_media resource type.

1. Create a group with the instance key marketing and the resource type teams.
2. Assign the editor role on social_media:training_video to the marketing group.
3. Add the marketing users to the group.

Every user in the marketing group, including users you add later, derives the editor role on social_media:training_video. Give a user group access to a resource instance sets up this example step by step.

Prerequisites

• An environment API key. See Get your API key.
• The keys or IDs of your project and environment. See Get the project and environment.
• A tenant for the group, the resource instances, and the users. A group, the resource instances it gets roles on, and its users must all use the same tenant.
• Familiarity with ReBAC in Permit.

Groups API endpoints

All paths start with https://api.permit.io/v2/schema/{proj_id}/{env_id}.

Task	Method and path	Notes
Create a group	POST /groups
List groups	GET /groups/direct	Use instead of the deprecated GET /groups
Get a group	GET /groups/direct/{group_instance_key}	Use instead of the deprecated GET /groups/{group_instance_key}
Delete a group	DELETE /groups/{group_instance_key}
Assign a role to a group	POST /groups/{group_instance_key}/roles
Remove a role from a group	DELETE /groups/{group_instance_key}/roles
List the roles of a group	GET /groups/{group_instance_key}/roles	Early access
Add a user to a group	PUT /groups/{group_instance_key}/users/{user_id}
Remove a user from a group	DELETE /groups/{group_instance_key}/users/{user_id}
List the users of a group	GET /groups/{group_instance_key}/users	Early access
Assign a group to a group	PUT /groups/{group_instance_key}/assign_group
Remove a group from a group	DELETE /groups/{group_instance_key}/assign_group
List child groups	GET /groups/{group_instance_key}/children	Early access
List parent groups	GET /groups/{group_instance_key}/parents	Early access

group_instance_key in a path has the format resource_type:instance, for example teams:marketing. The API reference marks the GET /groups and GET /groups/{group_instance_key} endpoints as deprecated. Use the /groups/direct endpoints for new code.

Give a user group access to a resource instance

This procedure sets up the marketing team example: members of the marketing group get the editor role on the training_video instance of social_media.

In every command, replace API_SECRET_KEY with your environment API key, and {proj_id} and {env_id} with your project and environment keys or IDs. The samples use the tenant default. Use one tenant key of your own in every call.

1. Create the group

Send a POST request with the group instance key, the resource type key, and the tenant. If you omit group_resource_type_key, the group's resource type is group.

curl 'https://api.permit.io/v2/schema/{proj_id}/{env_id}/groups' \
 -H 'authorization: Bearer API_SECRET_KEY' \
 -H 'Content-Type: application/json' \
 --data-raw '{"group_instance_key": "marketing", "group_resource_type_key": "teams", "group_tenant": "default"}'

2. Create the resource and resource instance

Create the social_media resource with the actions the group's members need. A resource with no actions grants nothing, so a later check against it always returns false:

curl 'https://api.permit.io/v2/schema/{proj_id}/{env_id}/resources' \
 -H 'authorization: Bearer API_SECRET_KEY' \
 -H 'Content-Type: application/json' \
 --data-raw '{"key": "social_media", "name": "social media", "actions": {"view": {"name": "view"}, "edit": {"name": "edit"}}}'

Create the training_video resource instance. Resource instances are facts objects, so the v2 path is /v2/facts/{proj_id}/{env_id}/resource_instances:

curl 'https://api.permit.io/v2/facts/{proj_id}/{env_id}/resource_instances' \
 -H 'authorization: Bearer API_SECRET_KEY' \
 -H 'Content-Type: application/json' \
 --data-raw '{"key": "training_video", "tenant": "default", "resource":"social_media"}'

3. Create the editor role

The role you assign to a group must be a role of the target resource type. permissions takes the action keys the role grants on that resource type, so the editor role below grants view and edit on any social_media instance. A role created without permissions grants nothing. For the resource role endpoint, see ReBAC API calls.

curl 'https://api.permit.io/v2/schema/{proj_id}/{env_id}/resources/social_media/roles' \
 -H 'authorization: Bearer API_SECRET_KEY' \
 -H 'Content-Type: application/json' \
 --data-raw '{"key": "editor", "name": "editor", "permissions": ["view", "edit"]}'

4. Assign the editor role to the group

Send a POST request to /groups/{group_instance_key}/roles with the resource type, the resource instance, the role, and the tenant. All four fields are required. The group instance key in the path uses the type:instance format, here teams:marketing.

curl 'https://api.permit.io/v2/schema/{proj_id}/{env_id}/groups/teams:marketing/roles' \
 -H 'authorization: Bearer API_SECRET_KEY' \
 -H 'Content-Type: application/json' \
 --data-raw '{"resource": "social_media", "resource_instance": "training_video", "role": "editor", "tenant": "default"}'

5. Add users to the group

Send a PUT request for each user, with the tenant in the body. In the path, the group instance key is teams:marketing and {user_id} is the user key or ID.

curl -X PUT \
'https://api.permit.io/v2/schema/{proj_id}/{env_id}/groups/teams:marketing/users/{user_id}' \
  -H 'authorization: Bearer API_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{"tenant": "default"}'

What Permit creates when you assign a role to a group

After step 4, Permit creates these objects:

• A role derivation from the member role on teams to the editor role on social_media.
• A relation between the teams resource type and the social_media resource type.
• A relationship between the teams:marketing instance and the social_media:training_video instance.

Every user with the member role on teams:marketing derives the editor role on social_media:training_video, including users you add to the group later.

6. Verify the group setup

List the roles of the group. The response includes the editor role on social_media:training_video.

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

List the users of the group. The response includes the users you added in step 5.

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

Then run permit.check() for a user you added in step 5, the edit action, and the social_media:training_video instance, in the default tenant. The check returns true, because the user's member role on teams:marketing derives the editor role on that instance, and editor grants edit. A check for an action the editor role doesn't grant returns false. See Check permissions.

Assign a group to another group

Assign one group to another group to build a group hierarchy, for example a support team inside an organization. In this example, the support group and the org1 group both use the default group resource type, and org1 is assigned to support.

Limitation: groups must share a resource type

You can assign a group only to a group of the same resource type. For example, you can assign group:org1 to group:support, but not to teams:marketing.

1. Create the two groups

Create the support group:

curl 'https://api.permit.io/v2/schema/{proj_id}/{env_id}/groups' \
  -H 'authorization: Bearer API_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{"group_instance_key": "support", "group_tenant": "default"}'

Create the org1 group:

curl 'https://api.permit.io/v2/schema/{proj_id}/{env_id}/groups' \
  -H 'authorization: Bearer API_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{"group_instance_key": "org1", "group_tenant": "default"}'

2. Assign one group to the other

Send a PUT request to /groups/{group_instance_key}/assign_group. The body holds the key of the other group in the type:instance format, here group:org1.

curl -X PUT \
  'https://api.permit.io/v2/schema/{proj_id}/{env_id}/groups/group:support/assign_group' \
  -H 'authorization: Bearer API_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{"group_instance_key": "group:org1"}'

When you assign org1 to support, Permit creates:

• A role derivation from the member role on group to the member role on group.
• A relation from the group resource type to itself.
• A relationship between the group:support instance and the group:org1 instance.

3. Verify the group hierarchy

List the child groups of a group:

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

List the parent groups of a group:

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

The child list of one group includes the other group, and the parent list of the other group includes the first group.

List and get groups

List all groups

List the groups in an environment as a flat, paginated list, without their hierarchy:

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

To filter the list, add the tenant, resource, or search query parameter. Use page and per_page (up to 100) to page through results.

Get a specific group

Get one group by its group instance key, for example teams:marketing:

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

The response holds the group resource type key, the group instance key, the tenant, and the group ID.

API reference

For request and response schemas of every Groups endpoint, see the Groups section of the Permit API reference.

Related pages

• Groups UI: manage groups in the Permit dashboard
• What is ReBAC?
• ReBAC API calls