Skip to main content
Version: 2.0.0

Policy Guard API

The Policy Guard API allows you to manage policies at the organization level. Policy Guards help enforce centralized control over permissions and roles across specific projects included in the policy.

For example, let's say you want to ensure that only admins can create documents, while all other roles are restricted to read-only access. To achieve this, you would create a Policy Guard that defines these permissions, assigning the "admin" role the ability to create documents, while restricting the "viewer" role to read-only access. This policy would then apply consistently across all projects included in the Policy Guard. Let's see how you can use the Policy Guard API for the example above.

Info

For more information on Policy Guards, see the Policy Guard documentation.

Example API Usage​

First, we'll create a new policy guard scope in order to define the scope of the policy guard.

Create a New Policy Guard Scope​

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

To retrieve details about a specific policy guard scope, use the scope's ID. This allows you to confirm its settings and ensure it's correctly configured.

Get a Policy Guard Scope by ID​

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

If you need to remove a policy guard scope, you can delete it by specifying its ID. This will remove all associated permissions and roles.

Delete a Policy Guard Scope​

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

To extend the policy guard to include a new project, you can associate it with the existing policy guard scope.

Assign a Project to a Policy Guard Scope​

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

If a project is no longer part of the policy guard, you can disassociate it by providing the project's detail. This will remove the project's permissions defined in the scope.

Remove a Project from a Policy Guard Scope​

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

For adding and removing permission rules, you need to provide the resource, role, action, and whether the action is allowed or not.

Add a Permission Rule to a Policy Guard Scope​

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

The resource_key, role_key, and action_key are unique identifiers for resources, roles, and actions. We use key to create and guard objects, as IDs are unique within each environment.

For adding ABAC rules, you can provide user set and resource set

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

Using ABAC rules, you can define user and resource sets to guard permissions based on their attributes. For locking a user set, specify the user set, resource, and action. For locking a resource set, specify the resource set, resource, action, and either a role or user set.

For exemple, if you will try to create rule with user set and role key, it will throw an error.

If you need to revoke permissions for a specific action, you can remove the corresponding permission rule. This is how you would revoke the "admin" role's ability to create documents.

Remove a Permission Rule from a Policy Guard Scope​

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

To view all permission rules associated with a specific policy guard scope, you can retrieve them using the scope's ID. This helps in auditing and understanding the current permissions in place.

List all Permission Rules for a Policy Guard Scope​

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

Contents