From 179a38a362d9d4ebcfdf5f4d48fd35c91227cdb6 Mon Sep 17 00:00:00 2001 From: Or Weis Date: Mon, 10 Feb 2025 12:34:17 +0200 Subject: [PATCH 1/2] Update sync-your-first-user-with-sdk.mdx Needed clarifications --- .../sync-your-first-user-with-sdk.mdx | 36 +++++++++++++++---- 1 file changed, 29 insertions(+), 7 deletions(-) diff --git a/docs/overview/sync-your-first-user-with-sdk.mdx b/docs/overview/sync-your-first-user-with-sdk.mdx index ef74dc15..df68a2ab 100644 --- a/docs/overview/sync-your-first-user-with-sdk.mdx +++ b/docs/overview/sync-your-first-user-with-sdk.mdx @@ -1,20 +1,26 @@ --- 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: Users are the name we use fort 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 craeteUser API or create/sync-User SDK call. +This should be done as part of your Authentication callback +- Newly added users would appear in the Direcoty under `All Tenants`. +- Assign roles to users to also link them to specific tenants. +- You can assign multipe users to multiple roles at multiple tenants +- You can use the bulk API to load mutliple users at once. + + > 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. @@ -161,6 +167,16 @@ are customized for that tenant. + +## Bulk user syncing +Our API also supports syncing and updating users en-masse. +See: +1. [Bulk `Create` User](https://api.permit.io/scalar#tag/bulk-operations/POST/v2/facts/{proj_id}/{env_id}/bulk/users) +2. [Bulk `Replace` User](https://api.permit.io/scalar#tag/bulk-operations/PUT/v2/facts/{proj_id}/{env_id}/bulk/users) +3. [Bulk `Assign Roles` to Users](https://api.permit.io/scalar#tag/bulk-operations/POST/v2/facts/{proj_id}/{env_id}/role_assignments/bulk) +4. [Bulk `Unassign Roles` to Users](https://api.permit.io/scalar#tag/bulk-operations/DELETE/v2/facts/{proj_id}/{env_id}/role_assignments/bulk) +5. [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 +185,12 @@ 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. From 0fd69a660a003c38bf0b0314b030b4331fd0555a Mon Sep 17 00:00:00 2001 From: Filip Grebowski Date: Mon, 10 Feb 2025 11:49:13 +0000 Subject: [PATCH 2/2] Small grammar and visual changes --- .../sync-your-first-user-with-sdk.mdx | 40 ++++++++++--------- 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/docs/overview/sync-your-first-user-with-sdk.mdx b/docs/overview/sync-your-first-user-with-sdk.mdx index df68a2ab..b1d24193 100644 --- a/docs/overview/sync-your-first-user-with-sdk.mdx +++ b/docs/overview/sync-your-first-user-with-sdk.mdx @@ -5,7 +5,10 @@ title: Sync your First User 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: Users are the name we use fort both human and machine identities. + +:::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"; @@ -13,17 +16,16 @@ import TimelineStep from "../../src/components/timeline/TimelineStep"; import TimelineWrapper from "../../src/components/timeline/TimelineWrapper"; ## TL;DR -Sync users on-the-fly by passing their unique ID to the craeteUser API or create/sync-User SDK call. -This should be done as part of your Authentication callback -- Newly added users would appear in the Direcoty under `All Tenants`. -- Assign roles to users to also link them to specific tenants. -- You can assign multipe users to multiple roles at multiple tenants -- You can use the bulk API to load mutliple users at once. +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. +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. -> 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. +--- ## When to sync your users? @@ -33,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) @@ -167,15 +172,15 @@ are customized for that tenant. - ## Bulk user syncing + Our API also supports syncing and updating users en-masse. -See: -1. [Bulk `Create` User](https://api.permit.io/scalar#tag/bulk-operations/POST/v2/facts/{proj_id}/{env_id}/bulk/users) -2. [Bulk `Replace` User](https://api.permit.io/scalar#tag/bulk-operations/PUT/v2/facts/{proj_id}/{env_id}/bulk/users) -3. [Bulk `Assign Roles` to Users](https://api.permit.io/scalar#tag/bulk-operations/POST/v2/facts/{proj_id}/{env_id}/role_assignments/bulk) -4. [Bulk `Unassign Roles` to Users](https://api.permit.io/scalar#tag/bulk-operations/DELETE/v2/facts/{proj_id}/{env_id}/role_assignments/bulk) -5. [Bulk `Delete` User](https://api.permit.io/scalar#tag/bulk-operations/DELETE/v2/facts/{proj_id}/{env_id}/bulk/users) + +- [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? @@ -185,7 +190,6 @@ 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.