ABAC API overview
Build attribute-based access control (ABAC) policies with the Permit REST API instead of the Policy Editor. This section is for developers who script or automate policy setup. This page defines the objects you create, lists their endpoints, and links the pages of the section in reading order.
Prerequisites
- An environment API key. See Get your API key.
- The ID or key of your project and environment. See Get the project and environment IDs.
- User and resource attributes defined in your environment. See Define attributes.
ABAC API concepts
An ABAC policy in Permit is made of three objects. You create condition sets first, then connect them with condition set rules.
| Object | What it is | Example |
|---|---|---|
| Condition | A boolean expression over attributes, built from logical operators (allOf, anyOf, not) and comparison operators (equals, in, greater-than, and others). | user.location is in ["US"] |
| User set | A condition set of type userset. It contains every user whose attributes match its conditions. | us_based_employees: users located in the US with the employee role |
| Resource set | A condition set of type resourceset. It contains every resource whose attributes match its conditions. | private_repos: repositories whose access attribute is private |
| Condition set rule | A grant of one permission (<resource>:<action>) to a user set on a resource set. | us_based_employees can repository:clone on private_repos |
A condition set rule is a separate object. It references a user set and a resource set by key, and it is not stored inside either condition set.
Build an ABAC policy through the API
- Define the attributes your conditions use on users and resources.
- Create a user set with
POST /v2/schema/{proj_id}/{env_id}/condition_setsand"type": "userset". - Create a resource set with the same endpoint and
"type": "resourceset". - Grant a permission to the user set on the resource set with
POST /v2/facts/{proj_id}/{env_id}/set_rules.
ABAC API endpoints
| Method | Path | Operation |
|---|---|---|
GET | /v2/schema/{proj_id}/{env_id}/condition_sets | List condition sets. Filter with the type query parameter (userset or resourceset). |
POST | /v2/schema/{proj_id}/{env_id}/condition_sets | Create a user set or a resource set. |
GET | /v2/schema/{proj_id}/{env_id}/condition_sets/{condition_set_id} | Get one condition set. |
PATCH | /v2/schema/{proj_id}/{env_id}/condition_sets/{condition_set_id} | Update a condition set. |
DELETE | /v2/schema/{proj_id}/{env_id}/condition_sets/{condition_set_id} | Delete a condition set. |
GET | /v2/facts/{proj_id}/{env_id}/set_rules | List condition set rules. Filter with user_set, permission, or resource_set. |
POST | /v2/facts/{proj_id}/{env_id}/set_rules | Assign a permission to a user set on a resource set. |
DELETE | /v2/facts/{proj_id}/{env_id}/set_rules | Unassign a permission from a user set on a resource set. |
Every request authenticates with your API key in the Authorization: Bearer <API_KEY> header. For request and response schemas, see Condition Sets and Condition Set Rules in the API reference.
Identify the project and environment in API paths
The {proj_id} and {env_id} path parameters accept either the unique ID or the key of the project and environment. For example, /v2/schema/default/production/condition_sets targets the production environment of the default project. You don't need a separate API call to look up the IDs when you know the keys.
Pages in this section
Read the pages in this order:
- Operators: the logical, comparison, reference, and object-match operators you can use in conditions.
- Building conditions: how to nest operators into valid condition expressions.
- Condition sets: create user sets and resource sets, including parent condition sets.
- Condition set rules: grant a permission to a user set on a resource set.
- Condition set rule examples: a complete user set, resource set, and rule for one policy.