Advanced Walkthroughs

docs/overview/advanced-authorization-queries.mdx

@@ -0,0 +1,140 @@
+---
+sidebar_position: 8
+title: Advanced Authorization Queries
+---
+
+Authorization plays a crucial role in managing secure access to your systems, and advanced queries can make this process more
+precise and powerful. In this guide, we’ll explore various methods to retrieve permissions, manage authorized users,
+and efficiently sync user data with Permit.
+
+import WhatsNext from "../../src/components/whats-next/WhatsNext";
+import TimelineStep from "../../src/components/timeline/TimelineStep";
+import TimelineWrapper from "../../src/components/timeline/TimelineWrapper";
+import Video from "../../src/components/video/Video";
+import CodeBlock from "../../src/components/code-block/CodeBlock";
+
+---
+
+To better understand the principles of the advanced authorization queries below, let's base all these below principles on an example.
+
+:::info
+**Alice** and **Bob** are users in a blogging application. Here’s how they interact with the blog posts:
+
+- Alice is the **author** of Blog Post 1 and Blog Post 2. She has full **edit** and **read** permissions for these posts.
+- Bob is the **author** of Blog Post 3, with full **edit** and **read** permissions for that post.
+- Alice and Bob can both view each other’s blog posts but cannot edit them.
+
+Let's put this to practice.
+:::
+
+:::tip **The Challenge**
+
+**Alice** and **Bob** need to query the system to:
+
+- Determine what permissions they have for specific blog posts.
+- Retrieve blog posts they are allowed to view or edit.
+- List the users who can perform actions on a given blog post.
+
+:::
+
+## Bulk Check
+
+The `permit.bulkCheck` function allows validating multiple permissions in a single call, ideal for situations where Alice or
+Bob needs to check permissions for multiple blog posts at once.
+
+### Example: Alice Checks Read Permissions
+
+Alice wants to know which blog posts she can read.
+
+<CodeBlock folderPath="/bulk-check" />
+
+Alice can read Blog Post 1, Blog Post 2, and Blog Post 3. The system returns this in one call, saving time and improving
+efficiency.
+
+You can read more about the bulk check [here](/how-to/enforce-permissions/bulk-check/).
+
+## FilterObjects
+
+Use the `permit.filterObjects` function to perform PDP-level filtering.
+
+In this method, the data is fetched from the DB, and then use the filterObjects function, which returns a subset of the objects
+passed to it based on the policy.
+
+The `permit.filterObjects` function retrieves only the blog posts that Alice or Bob is permitted to access. This is useful when fetching all posts from the database but only displaying the ones a user is authorized to see.
+
+### Example: Alice Filters Blog Posts
+
+Alice wants to retrieve the blog posts she can edit.
+
+```go
+resourcesToCheck := []enforcement.ResourceI{
+    enforcement.ResourceBuilder("blog_post").WithID("1"),
+    enforcement.ResourceBuilder("blog_post").WithID("2"),
+    enforcement.ResourceBuilder("blog_post").WithID("3"),
+}
+allowedResources, err = permit.FilterObjects(
+    user, "edit", requestContext, resourcesToCheck...
+)
+```
+
+The function returns Blog Post 1 and Blog Post 2, as Alice has edit permissions for these posts.
+
+## Get Authorized Users
+
+Use the `permit.authorized_users` function to retrieve a list of users authorized to perform a specific action on a resource.
+This function takes an action and resource as inputs and returns the authorized users along with their role assignments that
+granted access.
+
+### Example: Retrieve Authorized Users
+
+Bob wants to know who can read Blog Post 3.
+
+```bash
+POST /v2/schema/{proj_id}/{env_id}/resources/{resource_id}/authorized_users
+
+# Example Request
+curl https://api.permit.io/v2/schema/my_project/my_environment/resources/blog_post:3/authorized_users \
+  --request POST \
+  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
+  --data '{"action": "read"}'
+```
+
+The system responds with:
+
+- Alice (has read permissions).
+- Bob (has edit and read permissions).
+
+You can read more about getting resource authorized users [here](/how-to/enforce-permissions/authorized-users).
+
+## Get User Permissions
+
+Use the `permit.GetUserPermissions` function to retrieve all user permissions across all registered resources and tenants.
+Simply provide a "User" as input, optionally filter by a list of tenants, and receive an object detailing the permissions
+and attributes for each assigned tenant.
+
+### Example: Bob’s Permissions
+
+```bash
+POST /v2/schema/{proj_id}/{env_id}/users/{user_id}/permissions
+
+# Example Request
+curl https://api.permit.io/v2/schema/my_project/my_environment/users/[email protected]/permissions \
+  --request POST \
+  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
+```
+
+The system returns a list of Bob’s permissions:
+
+- Blog Post 1: Read
+- Blog Post 2: Read
+- Blog Post 3: Read, Edit
+
+You can read more about getting user permissions [here](/how-to/enforce-permissions/user-permissions).
+
+## What did you learn?
+
+:::tip FUN FACT
+Did you know? The concept of "authorization" dates back to ancient times when officials used wax seals on documents to verify
+permission. Today, we use advanced databases and APIs, but the goal remains the same—ensuring the right people have access to
+the right things.
+:::