Skip to main content
Version: 2.0.0

Local Enforcement APIs

Besides the standard check and data filtering functions, applications may require additional information such as role assignments, roles, tenants, etc.

To help your application perform these operations efficiently, Permit provides some of these APIs as part of the local PDP container. Using these APIs in the local PDP avoids network latency and provides faster responses.

API Availability

Permit is gradually releasing these APIs. The following pages contain the currently available APIs. If you want any additional function exposed from the PDP, please reach out to us in our Slack environment.

List Role Assignments​

This function is available from PDP container version permitio/pdp-v2:0.3.0 and above.

The permit.pdp_api.role_assignments.list function (or /local/role_assignments via the REST API) returns the list of role assignments from the local PDP. You can also use the advanced filters to return role assignments based on the user, tenant, resource, role, and resource instance.

The function accepts optional user_key, tenant_key, role_key, resource_instance_key filters, and returns a list of role assignments that match the filters.

The response contains a list of objects with the following fields:

  • user_key - The user to whom the role is assigned.
  • tenant_key - The tenant to which the role is assigned. In the case of a resource role, this represents the tenant that the resource instance is associated with.
  • role_key - The role assigned to the user.
  • resource_instance_key (Optional) - The resource instance to which the role is assigned.

The schema of the response is as follows:

[
    {
        "user": "jane@coolcompany.com",
        "role": "admin",
        "tenant": "stripe-inc"
    },
    {
        "user": "jane@coolcompany.com",
        "role": "admin",
        "tenant": "stripe-inc",
        "resource_instance": "document:doc-1234"
    }
]
Pagination

This function is paginated and returns a maximum of 100 role assignments per page.
You can use the page and per_page parameters to navigate through the pages.

Usage Examples​

While you can use the function directly to list all the assignments, you can also use one or more of the filters based on the user_key, tenant_key, role_key, resource_instance_key to filter the results. All those filters can be mixed together to provide more granular filtering.

List all role assignments​

This function call will return all role assignments from the local PDP.

from permit.models.pdp import RoleAssignmentRead

permissions: RoleAssignmentRead = permit.pdp_api.role_assignments.list();

Filter by user​

Another useful example is a call that filters the role assignments based on the user. This way, you can get all the roles assigned to a specific user and enforce the permissions based on them.

from permit.models.pdp import RoleAssignmentRead

permissions: RoleAssignmentRead = permit.pdp_api.role_assignments.list(
    user="John",
)

Filter by Resource Instance​

In the "opposite" way of the previous example, you can filter role assignments based on the resource instance. This way, you can get all the roles assigned to a specific resource instance and enforce the permissions based on them.

from permit.models.pdp import RoleAssignmentRead

permissions: RoleAssignmentRead = permit.pdp_api.role_assignments.list(
    resource_instance_key="document:onboarding-doc",
)

Contents