diff --git a/docs/versioned_docs/version-3.16.0-LTS/app-builder/pat-integration.md b/docs/versioned_docs/version-3.16.0-LTS/app-builder/pat-integration.md new file mode 100644 index 0000000000..85a1d65650 --- /dev/null +++ b/docs/versioned_docs/version-3.16.0-LTS/app-builder/pat-integration.md @@ -0,0 +1,165 @@ +--- +id: pat-integration +title: Using PAT for Embedded Apps +--- + +ToolJet’s Personal Access Tokens (PATs) allow you to securely embed your applications inside portals, dashboards, or third-party systems without requiring your users to log in again. + +This guide shows how to use PATs to create isolated, scoped sessions for embedded apps, so your users can interact with ToolJet apps seamlessly while your main application handles authentication. + +Key Benefits +- Embed apps without login prompts or redirects. +- Scoped access for each app and user. +- Session isolation ensures embedded sessions don’t interfere with normal ToolJet usage. +- Token expiration control for secure access. + +## Authentication Flow + +The embedding workflow involves your web application and ToolJet backend: +1. User logs into your portal using your preferred authentication method. +2. Your backend generates a PAT scoped to that user and app. +3. Backend returns an embed URL containing the PAT. +4. Frontend renders the ToolJet app inside an iframe using the embed URL. + +### Flow Diagram + +```js +User → Your App → Backend → ToolJet API → Backend → Frontend → iframe → ToolJet App +``` + +- Your app authenticates the user. +- Backend requests a PAT from ToolJet. +- ToolJet returns a secure redirect URL. +- Frontend embeds the app in an iframe using this URL. + +## Step 1 — Generate a PAT + +Use ToolJet’s PAT endpoint to create a token for a specific app–user pair. + +**Endpoint** +```js +POST /api/ext/users/personal-access-token +``` + +**Required Parameters** + +| Field | Type | Description | +| --------------- | ------ | ---------------------------------- | +| `email` | string | Email of the user | +| `appId` | string | App ID for which the PAT is scoped | +| `sessionExpiry` | number | Session duration in minutes | +| `patExpiry` | number | Token validity in seconds | + +**cURL Example** + +```bash +curl --location 'https://your-tooljet-domain.com/api/ext/users/personal-access-token' \ +--header 'Authorization: Basic ' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "email": "user@example.com", + "appId": "8ba8bf0e-6b8f-4e07-abb9-6fd2d816fabc", + "sessionExpiry": 60, + "patExpiry": 3600 +}' +``` + +**Node.js/Express Example** + +```js +import axios from 'axios'; + +const generatePAT = async (email, appId) => { + const response = await axios.post( + 'https://your-tooljet-domain.com/api/ext/users/personal-access-token', + { + email, + appId, + sessionExpiry: 60, + patExpiry: 3600 + }, + { + headers: { + 'Authorization': 'Basic ', + 'Content-Type': 'application/json' + } + } + ); + return response.data.redirectUrl; // Embed URL containing PAT +}; +``` + +## Step 2 — Create the Embed URL + +The response from ToolJet contains a redirectUrl or PAT. Use this to form the URL for embedding: + +```js +https://your-domain.com/embed-apps/:appId?personal-access-token=pat_XXXX +``` + +**How it works** + +1. PAT is validated by ToolJet. +2. A session is created isolated from your main ToolJet session. +3. The embedded app loads inside the iframe. + +## Step 3 — Render the App + +**Basic iframe** + +```js + +``` + +**React Example** + +```js +import React, { useEffect, useState } from 'react'; +import axios from 'axios'; + +const EmbeddedApp = ({ userEmail, appId }) => { + const [embedUrl, setEmbedUrl] = useState(''); + + useEffect(() => { + const fetchPAT = async () => { + const response = await axios.post('/api/generate-pat', { email: userEmail, appId }); + setEmbedUrl(response.data.redirectUrl); + }; + fetchPAT(); + }, [userEmail, appId]); + + return embedUrl ? ( +