Merge pull request #503 from permitio/orweis-patch-2

Update sync-your-first-user-with-sdk.mdx

docs/overview/sync-your-first-user-with-sdk.mdx

@@ -1,23 +1,31 @@
 ---
 sidebar_position: 2
-title: Sync your First User using the SDK
+title: Sync your First User
 ---
 
-Syncing a user is one of the most integral parts of using Permit, as it serves as the handoff point
-between your application's user management system and our policy engine.
+Syncing users is one of the most integral parts of using Permit, as it serves as the handoff point
+between your application's user management system (usually Authentication or IdP) and the Permit authorizaiton control-plane.
+
+:::note NOTE
+**`Users`** are the **name** we use for both **human** and **machine identities**.
+:::
 
 import CodeBlock from "../../src/components/code-block/CodeBlock";
 import WhatsNext from "../../src/components/whats-next/WhatsNext";
 import TimelineStep from "../../src/components/timeline/TimelineStep";
 import TimelineWrapper from "../../src/components/timeline/TimelineWrapper";
 
-:::tip
-Permit is fully API-driven, providing a seamless way to programmatically manage everything you can do via our
-no-code UI.
-:::
+## TL;DR
+
+Sync users on-the-fly by passing their unique ID to the `createUser` API or `users.create/sync` SDK call.
+This should be done as part of your Authentication callback.
 
-> In this guide, we’ll show you how to sync your first user into Permit using the API, ensuring they’re already assigned a role,
-> or ready to be assigned roles and permissions within your access control model.
+1. Newly added users would appear in the Directory under `All Tenants`.
+2. Assign roles to users to also link them to specific tenants.
+3. You can assign multiple users to multiple roles at multiple tenants.
+4. You can use the bulk API to load multiple users at once.
+
+---
 
 ## When to sync your users?
 
@@ -27,7 +35,10 @@ attributes, and relationships. This ensures their permissions align immediately
 
 ## Our API Reference
 
-In this guide we will be making use of two separate endpoint in our API:
+In this walkthrough, we’ll show you how to sync your first user into Permit using the API, ensuring they’re already assigned a
+role, or ready to be assigned roles and permissions within your access control model.
+
+We will be making use of two separate endpoint in our API:
 
 1. [Creating a user](https://api.permit.io/scalar#tag/users/POST/v2/facts/{proj_id}/{env_id}/users)
 2. [Assigning a role to a user](https://api.permit.io/scalar#tag/users/POST/v2/facts/{proj_id}/{env_id}/users/{user_id}/roles)
@@ -161,6 +172,16 @@ are customized for that tenant.
 </TimelineStep>
 </TimelineWrapper>
 
+## Bulk user syncing
+
+Our API also supports syncing and updating users en-masse.
+
+- [Bulk `Create` User](https://api.permit.io/scalar#tag/bulk-operations/POST/v2/facts/{proj_id}/{env_id}/bulk/users)
+- [Bulk `Replace` User](https://api.permit.io/scalar#tag/bulk-operations/PUT/v2/facts/{proj_id}/{env_id}/bulk/users)
+- [Bulk `Assign Roles` to Users](https://api.permit.io/scalar#tag/bulk-operations/POST/v2/facts/{proj_id}/{env_id}/role_assignments/bulk)
+- [Bulk `Unassign Roles` to Users](https://api.permit.io/scalar#tag/bulk-operations/DELETE/v2/facts/{proj_id}/{env_id}/role_assignments/bulk)
+- [Bulk `Delete` User](https://api.permit.io/scalar#tag/bulk-operations/DELETE/v2/facts/{proj_id}/{env_id}/bulk/users)
+
 ## What did you learn?
 
 In this guide, you’ve learned how to:
@@ -169,6 +190,11 @@ In this guide, you’ve learned how to:
 - Assign roles to a user either during creation or later through a dedicated API call.
 - Understand Permit’s hierarchy (workspaces, projects, environments) and how it relates to API calls.
 
+:::tip
+Permit is fully API-driven, providing a seamless way to programmatically manage everything you can do via our
+no-code UI.
+:::
+
 :::tip FUN FACT!
 Ever heard of the Cat Facts API? Developers created it as a joke, but it became a hit for testing API integrations while
 sending random cat facts.