We’ve introduced a new API endpoint to expand Permify Schema actions in a tree structure to improve observability and reasonability of access permissions.
Expand API is represented by a userset tree whose leaf nodes are user IDs or usersets pointing to other ⟨object#relation⟩ pairs, and intermediate nodes represent union, intersection, or exclusion operators.
Expand is crucial for our users to reason about the complete set of users and groups that have access to their objects, which allows them to build efficient search indices for access-controlled content. Unlike the Read API, Expand follows indirect references expressed through userset rewrite rules.
To give an example usage for Expand API, let's examine following authorization model.
Above schema - modeled with Permify's DSL - represents a simplified version of GitHub access control. When we look at the repository entity, we can see two actions and corresponding accesses:
- Only owners can push to a private repository.
- To read a private repository, the user should be one of the owners of that repository and need to belong to the parent organization of that repository ( user can either be admin or member on that organization).
Authorization data stored as relational tuples when using Permify. According to above authorization model, let's create 3 example relation tuples for testing expand API,
organization:1#admin@user:1 -->User 1 is admin in organization 1
repository:1#owner@user:1 -->User 1 is owner of repository 1
repository:1#parent@organization:1#... --> repository 1 belongs to organization 1
We can use expand API to reason the access actions. If we want to reason access structure for the read action of repository entity, we can use expand API with POST "/v1/permissions/expand".
In Permify, these relational tuples represents your authorization data. Since we have a model and data related with it, let's see expand API in action.
Request - POST "/v1/permissions/expand"
Response
Graph representation of JSON Response
