Manage Policy Guards with the API

Use the Permit API to create a Policy Guard scope, attach projects to it, and add the permission rules that every project in the scope enforces. This guide is for workspace administrators who call the Permit API from a terminal or a script. For what a Policy Guard is and how Permit applies it, see Policy Guards.

The example on this page makes sure only the admin role can create documents in every project in the scope.

Prerequisites

• An organization API key, or a Workspace Owner account. Other API keys get a 403 Forbidden error from the Policy Guard endpoints. See API key types.
• The ID of each project you want to guard. See Get the project ID.
• curl.

Placeholders in the requests

Placeholder	Replace with
API_SECRET_KEY	Your organization API key.
{policy_guard_scope_id}	The scope's id from the create response, or the scope's key (for example policy_guard_acme).
c3b6f5d7-8b1e-4c6d-9e9f-8c9d6f8e0c8f in project_id	The ID of your project.

Send request bodies as JSON with a Content-Type: application/json header. All endpoints are listed under Policy Guards (EAP) in the API reference.

Example API usage

1. Create a Policy Guard scope

A scope holds a unique key and the list of projects that the Policy Guard applies to. Send POST /v2/policy_guards/scopes:

Field	Required	Description
key	Yes	A unique key for the scope.
policy_guard_scope_details	No	A list of objects, each with a project_id. Permit marks every environment of each listed project as guarded.

curl -X POST 'https://api.permit.io/v2/policy_guards/scopes' \
-H 'authorization: Bearer API_SECRET_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{
    "key": "policy_guard_acme",
    "policy_guard_scope_details": [
        {
            "project_id": "c3b6f5d7-8b1e-4c6d-9e9f-8c9d6f8e0c8f"
        }
    ]
}'

The response is the scope object, with id, key, organization_id, and policy_guard_scope_details. Use the id or the key as {policy_guard_scope_id} in the next requests.

2. Get a Policy Guard scope

Send GET /v2/policy_guards/scopes/{policy_guard_scope_id} to confirm the scope's key and projects:

curl 'https://api.permit.io/v2/policy_guards/scopes/{policy_guard_scope_id}' \
-H 'authorization: Bearer API_SECRET_KEY'

The response has the same fields as the create response. To list all scopes in the organization, send GET /v2/policy_guards/scopes.

3. Add a project to a Policy Guard scope

Send POST /v2/policy_guards/scopes/{policy_guard_scope_id}/associate with the project_id of the project to add. Permit marks every environment of the project as guarded and applies the scope's rules to each environment.

curl -X POST 'https://api.permit.io/v2/policy_guards/scopes/{policy_guard_scope_id}/associate' \
-H 'authorization: Bearer API_SECRET_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{
    "project_id": "c3b6f5d7-8b1e-4c6d-9e9f-8c9d6f8e0c8f"
}'

Permit applies the rules in a background task. The response is a task object with task_id and status (processing, success, failure, or cancelled). To wait for the task to finish before the response returns, add the wait query parameter with a number of seconds, for example ?wait=10.

4. Add a role-based permission rule

Send POST /v2/policy_guards/scopes/{policy_guard_scope_id}/rules to add a rule. This rule allows the admin role to create on the documents resource in every environment of every project in the scope:

Field	Required	Description
resource_key	Yes	The key of the resource. Permit creates the resource in an environment where it doesn't exist.
action_key	Yes	The key of the action.
is_allowed	Yes	true grants the permission. Permit locks the permission from edits in the guarded environments.
role_key	No	The key of the role.
user_set	No	A user set, as an object with key, attribute, operator, and value.
resource_set	No	A resource set, as an object with key, attribute, operator, and value.

curl -X POST 'https://api.permit.io/v2/policy_guards/scopes/{policy_guard_scope_id}/rules' \
-H 'authorization: Bearer API_SECRET_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{
    "resource_key": "documents",
    "role_key": "admin",
    "action_key": "create",
    "is_allowed": true
}'

Rules use keys, not IDs, because IDs are unique to each environment. A key refers to the same resource, role, or action in every environment of the scope. The response is a task object, as in the previous step. Adding a rule that already exists in the scope returns a conflict error.

5. Add an attribute-based permission rule

Attribute-based access control (ABAC) rules use a user set, a resource set, or both, instead of a role. This rule allows users whose email contains permit to create documents:

curl -X POST 'https://api.permit.io/v2/policy_guards/scopes/{policy_guard_scope_id}/rules' \
-H 'authorization: Bearer API_SECRET_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{
    "resource_key": "documents",
    "user_set": {
        "key": "user_set_email",
        "attribute": "email",
        "value": "permit",
        "operator": "contains"
    },
    "action_key": "create",
    "is_allowed": true
}'

Each rule needs resource_key and action_key, plus one of these combinations:

To guard	Set
A role	role_key
A user set	user_set
A resource set for a role	resource_set and role_key
A resource set for a user set	resource_set and user_set

A rule with both role_key and user_set and no resource_set fails with a 400 Bad Request error.

6. List the rules of a Policy Guard scope

Send GET /v2/policy_guards/scopes/{policy_guard_scope_id}/rules to see every rule the scope enforces. The rules you added appear in the response array, each with its id, scope_id, and rule fields.

curl 'https://api.permit.io/v2/policy_guards/scopes/{policy_guard_scope_id}/rules' \
-H 'authorization: Bearer API_SECRET_KEY'

Remove rules, projects, and scopes

Remove a permission rule

Send DELETE /v2/policy_guards/scopes/{policy_guard_scope_id}/rules with the same resource_key, action_key, and role_key, user_set, or resource_set that you used to create the rule. This request removes the rule that locks the admin role's permission to create documents:

curl -X DELETE 'https://api.permit.io/v2/policy_guards/scopes/{policy_guard_scope_id}/rules' \
-H 'authorization: Bearer API_SECRET_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{
    "resource_key": "documents",
    "role_key": "admin",
    "action_key": "create"
}'

A successful request returns 204 No Content. If no rule in the scope matches the body, the API returns 404 Not Found.

Remove a project from a Policy Guard scope

Send DELETE /v2/policy_guards/scopes/{policy_guard_scope_id}/disassociate with the project_id. Permit marks the project's environments as no longer guarded, so project members can edit the permissions again.

curl -X DELETE 'https://api.permit.io/v2/policy_guards/scopes/{policy_guard_scope_id}/disassociate' \
-H 'authorization: Bearer API_SECRET_KEY' \
-H 'Content-Type: application/json' \
--data-raw '{
    "project_id": "c3b6f5d7-8b1e-4c6d-9e9f-8c9d6f8e0c8f"
}'

A successful request returns 204 No Content.

Delete a Policy Guard scope

Send DELETE /v2/policy_guards/scopes/{policy_guard_scope_id} to delete the scope. A successful request returns 204 No Content.

curl -X DELETE 'https://api.permit.io/v2/policy_guards/scopes/{policy_guard_scope_id}' \
-H 'authorization: Bearer API_SECRET_KEY'

Next steps

• Policy Guards: scopes, rules, and how Permit applies them
• Policy Guards (EAP) endpoints in the API reference
• Build ABAC policies with user sets and resource sets
• API key types