Create condition sets with the API

Create the user sets and resource sets of an attribute-based access control (ABAC) policy with the Permit API. This page is for developers who script policy setup. It defines both set types, shows the request body for each, and explains parent condition sets. For the concepts behind this section, see the ABAC API overview.

A condition set is a group of users or resources defined by conditions on their attributes, instead of by a fixed list. You grant permissions to condition sets the same way you grant permissions to roles in role-based access control (RBAC).

There are two types of condition sets:

Type	type value	Contains
User set	userset	Every user whose attributes match all of the set's conditions
Resource set	resourceset	Every resource whose attributes match all of the set's conditions

Prerequisites

• An environment API key. See Get your API key.
• The user and resource attributes that your conditions reference. See Define attributes.
• Familiarity with the conditions object. See Build ABAC conditions.

Example user set: US-based employees

US-based employees

All users who are located in the United States and have the employee role.

The key of this user set is us_based_employees.

Example resource set: private repositories

Private repositories

All resources of type repository that are private.

The key of this resource set is private_repos.

A condition set rule connects a user set to a resource set. The following matrix grants us_based_employees permissions on the Private Repositories resource set. The other cells have no grant.

	Admin	Employee	Employee in the US
Private Repositories			X
Marketing Materials

Create a condition set

Send the condition set as the JSON body of a POST request to https://api.permit.io/v2/schema/{proj_id}/{env_id}/condition_sets, with the header Authorization: Bearer <API_KEY>. The {proj_id} and {env_id} path parameters accept an ID or a key.

Field	Required	Description
key	Yes	Unique identifier of the condition set. Condition set rules reference the set by this key.
name	Yes	Display name, for example US based employees.
type	No	userset (default) or resourceset.
conditions	No	The boolean expression that decides membership. See Build ABAC conditions.
resource_id	For resource sets	For a resource set, the ID or key of the resource the set is based on.
parent_id	No	The ID or key of a parent condition set. See Condition set hierarchy.
description	No	A longer description of the set.

User set body for US-based employees

Both conditions must be true, so the conditions use the allOf logical operator. The type is userset.

us_based_employees

{
    "key": "us_based_employees",
    "name": "US based employees",
    "type": "userset",
    "conditions": {
        "allOf": [
            {
                "user.role": {
                    "equals": "employee"
                }
            },
            {
                "user.location": {
                    "in": [
                        "US"
                    ]
                }
            }
        ]
    }
}

Resource set body for private repositories

The resource set uses the same structure with type set to resourceset.

private_repos

{
    "key": "private_repos",
    "name": "Private Repositories",
    "type": "resourceset",
    "resource_id": "repository",
    "conditions": {
        "allOf": [
            {
                "resource.type": {
                    "equals": "repository"
                }
            },
            {
                "resource.access": {
                    "equals": "private"
                }
            }
        ]
    }
}

Verify the condition set

Send a GET request to https://api.permit.io/v2/schema/{proj_id}/{env_id}/condition_sets/{condition_set_id}, with the set's key as {condition_set_id}. The response contains the set's key, type, and conditions, plus the id, created_at, and updated_at fields that Permit assigns.

To list all sets of one type, send a GET request to /v2/schema/{proj_id}/{env_id}/condition_sets?type=userset or ?type=resourceset.

Condition set hierarchy

A condition set can have an optional parent condition set, set with parent_id. A set with a parent applies all of its parent's conditions in addition to its own conditions (logical AND). A hierarchy can have several levels, and the resulting condition includes the conditions of every ancestor.

The API rejects a parent that has a different type from the child set, or a different resource_id.

The following resource set has the private repositories set as its parent, and matches private repositories that are archived:

private_archived_repos

{
    "key": "private_archived_repos",
    "name": "Private Archived Repositories",
    "type": "resourceset",
    "resource_id": "repository",
    "parent_id": "private_repos",
    "conditions": {
        "allOf": [
            {
                "resource.type": {
                    "equals": "repository"
                }
            },
            {
                "resource.archived": {
                    "equals": true
                }
            }
        ]
    }
}

To list a set's parents or children, send a GET request to /v2/schema/{proj_id}/{env_id}/condition_sets/{condition_set_id}/ancestors or /descendants.

Next steps

• Grant permissions with condition set rules on the user set and resource set you created.
• Walk through a complete example with a user set, a resource set, and a rule.