docs: add new permit.io docs (#1160)

Author: danielbass37

docs/integrations/authorization/permit.io/README.mdx

@@ -0,0 +1,165 @@
+---
+slug: /integrations/permit.io
+sidebar_label: Permit.io
+sidebar_custom_props:
+  description: Integrate Logto with Permit.io.
+---
+
+# Set up authorization with Permit.io
+
+[Permit.io](https://permit.io/) is an authorization platform that provides fine-grained access control for applications. You can use Logto in conjunction with Permit.io to manage user authentication and authorization.
+
+:::tip
+To understand the key differences between authentication and authorization, see [Authentication vs. authorization](/concepts/authn-vs-authz).
+:::
+
+This guide will show you how to connect Logto with Permit.io to implement authorization in your application.
+
+## Prerequisites
+
+- A [Logto Cloud](https://cloud.logto.io/) account or a [self-hosted Logto](https://docs.logto.io/introduction/set-up-logto-oss).
+- A Next.js application with Logto authentication already set up (follow our [Next.js guide](https://docs.logto.io/quick-starts/next) if you haven't)
+- A [Permit.io](https://app.permit.io/) account. Follow the official [Permit.io quickstart guide](https://docs.permit.io/quickstart/) to set up your Permit.io project before proceeding.
+
+## Integration \{#integration}
+
+### Install Permit.io SDK \{#install-permitio-sdk}
+
+Add the Permit.io SDK to your application:
+
+```bash
+npm install permitio
+```
+
+### Create a Permit.io project \{#create-a-permitio-project}
+
+1. Sign up for a free account at [permit.io](https://app.permit.io/)
+2. Create a new project and obtain your API key
+3. Add the API key to your environment variables:
+
+```bash
+PERMIT_API_KEY=your-permit-api-key
+```
+
+### Set up Permit.io client \{#set-up-permitio-client}
+
+Create a file to handle the Permit.io integration:
+
+```jsx
+// libraries/permit.js
+const { Permit } = require('permitio');
+
+// Initialize the Permit.io client
+const permit = new Permit({
+  pdp: 'https://cloudpdp.api.permit.io',
+  token: 'your-permitio-api-key',
+});
+
+// Sync a user with Permit.io
+export const syncUserToPermit = async (userId, email, firstName, lastName, role = 'viewer') => {
+  // First, sync the user
+  await permit.api.syncUser({
+    key: userId,
+    email: email || undefined,
+    first_name: firstName || undefined,
+    last_name: lastName || undefined,
+  });
+
+  // Then assign a role to the user
+  await permit.api.assignRole({
+    user: userId,
+    role: role,
+    tenant: 'default',
+  });
+
+  return true;
+};
+```
+
+### Create a Logto webhook for user registration \{#create-a-logto-webhook-for-user-registration}
+
+Logto provides [webhooks](/developers/webhooks) that can notify your application when events occur. We'll use the `PostRegister` webhook to [sync users to Permit.io](https://docs.permit.io/authentication/permit-and-authentication) when they sign up.
+
+Create a webhook endpoint in your application:
+
+```jsx
+// pages/api/webhooks/logto.js
+import { syncUserToPermit } from '../../../libraries/permit';
+
+export default async function handler(req, res) {
+  // Log the webhook payload for debugging
+  console.log('Webhook payload:', req.body);
+
+  const { event, user } = req.body;
+
+  // Process user registration events
+  if (event === 'PostRegister') {
+    try {
+      // Determine the user's role (you can implement your own logic here)
+      let role = 'viewer'; // Default role
+
+      // Sync the user to Permit.io
+      await syncUserToPermit(user.id, user.primaryEmail, user.name, undefined, role);
+
+      return res.status(200).json({ success: true });
+    } catch (error) {
+      console.error('Error syncing user:', error);
+      return res.status(500).json({ error: 'Failed to sync user' });
+    }
+  }
+
+  return res.status(200).json({ message: 'Event ignored' });
+}
+```
+
+### Configure the webhook in Logto Console \{#configure-the-webhook-in-logto-console}
+
+1. Go to the Webhooks section in your Logto Console
+2. Click "Create Webhook"
+3. Give your webhook a name
+4. Enter your endpoint URL (e.g., `https://your-app.com/api/webhooks/logto`)
+5. Select the `PostRegister` event
+6. Save the webhook
+
+:::note
+For local development, you can use tools like [ngrok](https://ngrok.com/) to expose your local server to the internet.
+:::
+
+### Test user sync \{#test-user-sync}
+
+To test that users are being synced correctly:
+
+1. Create a new user account in your application
+2. Check the Permit.io dashboard under "Directory" → "Users" to verify the user was synced
+3. Verify that the correct role was assigned to the user upon sign-up
+
+![Logto users synced to Permit.io with role assignments](./permitio.png)
+
+### Use Permit.io for authorization \{#use-permitio-for-authorization}
+
+Once users are synced, you can use Permit.io to check permissions:
+
+```jsx
+// Example of checking a permission
+const isPermitted = await permit.check(userId, 'view', 'reports');
+
+if (isPermitted) {
+  // User is allowed to view resources
+  // Show the resources UI
+} else {
+  // User is not allowed to view resources
+  // Show an access denied message
+}
+```
+
+## Conclusion \{#conclusion}
+
+You've successfully connected Logto with Permit.io to automatically sync users and implement authorization in your application. With this integration:
+
+1. Users authenticate through Logto
+2. New users are automatically synced to Permit.io via webhooks
+3. You can use Permit.io to check permissions and implement access control
+
+This setup provides a strong foundation for implementing more advanced authorization patterns as your application grows.
+
+For more advanced authorization use cases, explore [Permit.io's documentation](https://docs.permit.io/) on creating policies, enforcing permissions, and implementing role-based access control.

docs/integrations/authorization/permit.io/permitio.png

@@ -31,6 +31,13 @@ const integrations: SidebarConfig = [
     className: 'sidebar-section',
   },
   { type: 'autogenerated', dirName: 'integrations/sso' },
+  {
+    type: 'link',
+    label: 'Authorization',
+    href: '#',
+    className: 'sidebar-section',
+  },
+  { type: 'autogenerated', dirName: 'integrations/authorization' },
 ];
 
 export default integrations;