diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc
index cb2195968b2e..cff18b3eaeb4 100644
--- a/.markdownlint.jsonc
+++ b/.markdownlint.jsonc
@@ -13,5 +13,6 @@
     },
     "MD004": {
         "style": "dash" // Enforce "dash" style for unordered list items (e.g., "- item")
-    }
+    },
+    "MD024": { "siblings_only": true } // Allow duplicate headings in different sections
 }
diff --git a/docs/ai-agents/embedded/api/README.md b/docs/ai-agents/embedded/api/README.md
index 40fa46f1feeb..0d7e059af15b 100644
--- a/docs/ai-agents/embedded/api/README.md
+++ b/docs/ai-agents/embedded/api/README.md
@@ -1,5 +1,7 @@
 ---
+
 products: embedded
+
 ---
 
 # Airbyte API
@@ -11,15 +13,17 @@ The Airbyte API allows you to build a fully integrated Airbyte Embedded Experien
 Follow these steps to implement Airbyte Embedded with the API:
 
 ### 1. One-Time Setup (Your Organization)
+
 First, configure the foundation for your embedded integration:
 
 1. **[Create Connection Templates](./connection-templates.md)**: Define where your users' data will be stored (destination configuration)
 2. **[Create Source Templates](./source-templates.md)**: Choose which data connectors your users can access
 
 ### 2. Per-User Integration (Runtime)
+
 For each user who wants to connect their data:
 
-3. **[Generate User Tokens & Configure Sources](./configuring-sources.md)**: Authenticate users and collect their source credentials
+1. **[Generate User Tokens & Configure Sources](./configuring-sources.md)**: Authenticate users and collect their source credentials
 
 This approach separates one-time organizational setup from per-user operations, making your integration more scalable.
 
diff --git a/docs/ai-agents/embedded/api/authentication.md b/docs/ai-agents/embedded/api/authentication.md
new file mode 100644
index 000000000000..980e44f2f287
--- /dev/null
+++ b/docs/ai-agents/embedded/api/authentication.md
@@ -0,0 +1,586 @@
+# Authentication
+
+The Airbyte Embedded API uses a hierarchical authentication system with three types of tokens, each designed for specific use cases and security requirements.
+
+## Token types overview
+
+| Token Type | Use Case | Scope | Access Level |
+|------------|----------|-------|--------------|
+| **Operator Bearer Token** | Organization management, template creation | Organization-wide | Full access to organization resources |
+| **Scoped Token** | API integration, programmatic workspace access | Single workspace | Limited to specific workspace |
+| **Widget Token** | Embedded widget integration | Single workspace + origin validation | Limited to specific workspace with CORS protection |
+
+## Operator bearer token
+
+The Operator Bearer Token provides full organization-level access and is used for administrative operations.
+
+### Use cases
+
+- Creating and managing source templates
+- Creating and managing connection templates
+- Managing workspaces across the organization
+- Generating scoped tokens and widget tokens
+- Administrative API operations
+
+### Usage
+
+Include the operator token in the `Authorization` header:
+
+```bash
+curl https://api.airbyte.ai/api/v1/integrations/templates/sources \
+
+  -H 'Authorization: Bearer <your_operator_token>' \
+  -H 'Content-Type: application/json'
+
+```
+
+### Security best practices
+
+- **Never expose operator tokens in client-side code**
+- Store securely in secrets management system
+- Use scoped tokens for end-user operations
+- Rotate tokens periodically
+- Limit token distribution to trusted administrators only
+
+## Scoped token
+
+Scoped tokens provide workspace-level access and are designed for allowing end-users to create and edit sources in their workspace.
+
+### Use cases
+
+- API integrations for managing sources within a specific workspace
+- Multi-tenant applications with isolated workspaces
+
+### Features
+
+- Workspace-scoped access (cannot access other workspaces)
+- Automatically creates workspace from a workspace name if it doesn't exist
+- Region selection support
+- Embedded in JWT with `io.airbyte.auth.workspace_scope` claim
+
+### Generate scoped token
+
+#### Endpoint
+
+```bash
+POST https://api.airbyte.ai/api/v1/embedded/scoped-token
+
+```
+
+#### Authentication
+
+Requires **Operator Bearer Token**
+
+#### Request body
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `workspace_name` | string | Yes | Name of the workspace to create or use |
+| `region_id` | UUID | No | Region where workspace should be created (defaults to US) |
+
+#### Region ids
+
+| Region | Region ID |
+|--------|-----------|
+| US (Default) | `645a183f-b12b-4c6e-8ad3-99e165603450` |
+| EU | `b9e48d61-f082-4a14-a8d0-799a907938cb` |
+
+#### Request example
+
+**Create scoped token for US workspace:**
+
+```bash
+curl -X POST https://api.airbyte.ai/api/v1/embedded/scoped-token \
+
+  -H 'Authorization: Bearer <your_operator_token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+
+    "workspace_name": "customer_workspace_123"
+  }'
+
+```
+
+**Create scoped token for EU workspace:**
+
+```bash
+curl -X POST https://api.airbyte.ai/api/v1/embedded/scoped-token \
+
+  -H 'Authorization: Bearer <your_operator_token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+
+    "workspace_name": "eu_customer_workspace",
+    "region_id": "b9e48d61-f082-4a14-a8d0-799a907938cb"
+  }'
+
+```
+
+#### Response example
+
+```json
+{
+  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+}
+
+```
+
+#### Behavior notes
+
+- If the workspace already exists, returns a token for the existing workspace
+- If the workspace doesn't exist:
+  - Checks if a workspace with the same name exists in Airbyte Cloud
+  - If found in cloud, creates local database record
+  - If not found, creates new workspace in both Airbyte Cloud and local database
+- The `region_id` is only used when creating a new workspace
+
+### Using scoped tokens
+
+Once generated, use scoped tokens to access workspace-specific endpoints:
+
+```bash
+# List sources in the workspace
+curl https://api.airbyte.ai/api/v1/embedded/sources \
+
+  -H 'Authorization: Bearer <scoped_token>'
+
+# Create a source
+curl -X POST https://api.airbyte.ai/api/v1/embedded/sources \
+
+  -H 'Authorization: Bearer <scoped_token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+
+    "source_template_id": "template-123",
+    "name": "My Data Source"
+  }'
+
+```
+
+### Get scoped token information
+
+Retrieve organization and workspace information from a scoped token.
+
+#### Endpoint
+
+```bash
+GET https://api.airbyte.ai/api/v1/embedded/scoped-token/info
+
+```
+
+#### Authentication
+
+Requires **Scoped Token**
+
+#### Request example
+
+```bash
+curl https://api.airbyte.ai/api/v1/embedded/scoped-token/info \
+
+  -H 'Authorization: Bearer <scoped_token>'
+
+```
+
+#### Response example
+
+```json
+{
+  "organization_id": "12345678-1234-1234-1234-123456789012",
+  "workspace ID": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890"
+}
+
+```
+
+## Widget token
+
+Widget tokens are specialized tokens designed for embedded widget integration with enhanced security features.
+
+### Use cases
+
+- Embedding the Airbyte configuration widget in your application
+- Providing end-users with a UI to configure data sources
+- Multi-tenant applications with isolated workspaces
+
+### Features
+
+- All features of scoped tokens
+- **Origin validation** for CORS protection via `allowed_origin`
+- **Template filtering** via tags (both source and connection templates)
+- Base64-encoded payload containing token and pre-configured widget URL
+- Tag selection modes: `any` (at least one tag) or `all` (all tags required)
+
+### Generate widget token
+
+#### Endpoint
+
+```bash
+POST https://api.airbyte.ai/api/v1/embedded/widget-token
+
+```
+
+#### Authentication
+
+Requires **Operator Bearer Token**
+
+#### Request body
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `workspace_name` | string | Yes | - | Name of the workspace to create or use |
+| `allowed_origin` | string | Yes | - | The allowed origin for CORS (for example, `https://yourapp.com`) |
+| `region_id` | UUID | No | US region | Region where workspace should be created |
+| `selected_source_template_tags` | array of strings | No | `[]` | Tags to filter which source templates are available |
+| `selected_source_template_tags_mode` | string | No | `any` | Tag selection mode: `any` or `all` |
+| `selected_connection_template_tags` | array of strings | No | `[]` | Tags to filter which connection templates are available |
+| `selected_connection_template_tags_mode` | string | No | `any` | Tag selection mode: `any` or `all` |
+
+#### Tag selection modes
+
+| Mode | Behavior | Example |
+|------|----------|---------|
+| `any` | Template must have **at least one** of the specified tags | Tags: `["crm", "sales"]` matches templates with either "crm" OR "sales" |
+| `all` | Template must have **all** of the specified tags | Tags: `["crm", "sales"]` matches only templates with both "crm" AND "sales" |
+
+#### Request examples
+
+**Basic widget token:**
+
+```bash
+curl -X POST https://api.airbyte.ai/api/v1/embedded/widget-token \
+
+  -H 'Authorization: Bearer <your_operator_token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+
+    "workspace_name": "customer_workspace_123",
+    "allowed_origin": "https://yourapp.com"
+  }'
+
+```
+
+**Widget token with source template filtering:**
+
+```bash
+curl -X POST https://api.airbyte.ai/api/v1/embedded/widget-token \
+
+  -H 'Authorization: Bearer <your_operator_token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+
+    "workspace_name": "customer_workspace_123",
+    "allowed_origin": "https://yourapp.com",
+    "selected_source_template_tags": ["crm", "sales"],
+    "selected_source_template_tags_mode": "any"
+  }'
+
+```
+
+**Widget token with both source and connection template filtering:**
+
+```bash
+curl -X POST https://api.airbyte.ai/api/v1/embedded/widget-token \
+
+  -H 'Authorization: Bearer <your_operator_token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+
+    "workspace_name": "customer_workspace_123",
+    "allowed_origin": "https://yourapp.com",
+    "selected_source_template_tags": ["crm"],
+    "selected_source_template_tags_mode": "any",
+    "selected_connection_template_tags": ["standard-sync"],
+    "selected_connection_template_tags_mode": "all",
+    "region_id": "b9e48d61-f082-4a14-a8d0-799a907938cb"
+  }'
+
+```
+
+#### Response example
+
+```json
+{
+  "token": "eyJ0b2tlbiI6ImV5SmhiR2NpT2lKSVV6STFOaUlzSW5SNWNDSTZJa3BYVkNKOS4uLiIsIndpZGdldFVybCI6Imh0dHBzOi8vYXBwLmFpcmJ5dGUuYWkvcXVpY2stc3RhcnQvd2lkZ2V0P3dvcmtzcGFjZUlkPWExYjJjM2Q0LWU1ZjYtNzg5MC1hYjEyLWNkMzRlZjU2Nzg5MCZhbGxvd2VkT3JpZ2luPWh0dHBzOi8veW91cmFwcC5jb20ifQ=="
+}
+
+```
+
+### Using widget tokens
+
+The widget token is a base64-encoded JSON object containing:
+
+1. **Scoped token** - For API authentication
+2. **Widget URL** - Pre-configured URL with workspace ID, origin, and template filters
+
+#### Decode widget token
+
+```javascript
+// Example: Decode widget token in JavaScript
+const decodedToken = JSON.parse(atob(widgetToken));
+
+console.log(decodedToken.token);      // Scoped token for API calls
+console.log(decodedToken.widgetUrl);  // URL to load the widget
+
+```
+
+#### Embed widget
+
+```html
+<!-- Embed the Airbyte widget in an iframe -->
+<iframe
+  id="airbyte-widget"
+  src=""
+  width="100%"
+  height="600px"
+  frameborder="0">
+</iframe>
+
+<script>
+  // Decode the widget token received from your backend
+  const widgetToken = "eyJ0b2tlbiI6..."; // From API response
+  const decoded = JSON.parse(atob(widgetToken));
+
+  // Set the iframe src to the pre-configured widget URL
+  document.getElementById('airbyte-widget').src = decoded.widgetUrl;
+</script>
+
+```
+
+### Template filtering with tags
+
+Widget tokens support filtering both source templates and connection templates using tags. This allows you to customize which connectors and sync configurations are available to specific users or customer tiers.
+
+#### Use cases
+
+**Tier-based access:**
+
+```json
+{
+  "workspace_name": "free_tier_customer",
+  "allowed_origin": "https://yourapp.com",
+  "selected_source_template_tags": ["free-tier"],
+  "selected_source_template_tags_mode": "any"
+}
+
+```
+
+**Industry-specific connectors:**
+
+```json
+{
+  "workspace_name": "healthcare_customer",
+  "allowed_origin": "https://yourapp.com",
+  "selected_source_template_tags": ["healthcare", "hipaa-compliant"],
+  "selected_source_template_tags_mode": "all"
+}
+
+```
+
+**Feature gating:**
+
+```json
+{
+  "workspace_name": "beta_customer",
+  "allowed_origin": "https://yourapp.com",
+  "selected_source_template_tags": ["stable", "beta"],
+  "selected_source_template_tags_mode": "any",
+  "selected_connection_template_tags": ["premium-features"],
+  "selected_connection_template_tags_mode": "any"
+}
+
+```
+
+## Authentication flow patterns
+
+### Pattern 1: direct API integration
+
+For backend services or API integrations:
+
+1. Store **Operator Bearer Token** securely in your backend
+2. Generate **Scoped Token** for each customer workspace
+3. Use scoped token for all workspace-specific API calls
+4. Refresh scoped tokens when they expire (they expire after 20 minutes)
+
+```bash
+# 1. Generate scoped token (once per workspace)
+SCOPED_TOKEN=$(curl -X POST https://api.airbyte.ai/api/v1/embedded/scoped-token \
+
+  -H "Authorization: Bearer $OPERATOR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"workspace_name": "customer_123"}' | jq -r '.token')
+
+# 2. Use scoped token for operations
+curl https://api.airbyte.ai/api/v1/embedded/sources \
+
+  -H "Authorization: Bearer $SCOPED_TOKEN"
+
+```
+
+### Pattern 2: embedded widget integration
+
+For embedding the Airbyte UI in your application:
+
+1. Store **Operator Bearer Token** in your backend
+2. Create API endpoint in your backend to generate widget tokens
+3. Generate **Widget Token** with appropriate tags and origin
+4. Return widget token to frontend
+5. Frontend decodes token and loads widget
+
+```javascript
+// Backend endpoint (Node.js example)
+app.post('/api/airbyte/widget-token', async (req, res) => {
+  const { customerId, tier } = req.body;
+
+  // Determine tags based on customer tier
+  const tags = tier === 'premium' ? ['all'] : ['free-tier'];
+
+  const response = await fetch('https://api.airbyte.ai/api/v1/embedded/widget-token', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${process.env.AIRBYTE_OPERATOR_TOKEN}`,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      workspace_name: `customer_${customerId}`,
+      allowed_origin: 'https://yourapp.com',
+      selected_source_template_tags: tags,
+      selected_source_template_tags_mode: 'any'
+    })
+  });
+
+  const data = await response.json();
+  res.json({ widgetToken: data.token });
+});
+
+// Frontend code
+async function loadAirbyteWidget(customerId, tier) {
+  // Get widget token from your backend
+  const response = await fetch('/api/airbyte/widget-token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ customerId, tier })
+  });
+
+  const { widgetToken } = await response.json();
+
+  // Decode and load widget
+  const decoded = JSON.parse(atob(widgetToken));
+  document.getElementById('airbyte-widget').src = decoded.widgetUrl;
+}
+
+```
+
+### Pattern 3: multi-region support
+
+For applications serving users in different regions:
+
+```bash
+# Determine region based on customer location
+REGION_ID="645a183f-b12b-4c6e-8ad3-99e165603450"  # US
+# REGION_ID="b9e48d61-f082-4a14-a8d0-799a907938cb"  # EU
+
+curl -X POST https://api.airbyte.ai/api/v1/embedded/scoped-token \
+
+  -H "Authorization: Bearer $OPERATOR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "{
+
+    \"workspace_name\": \"customer_workspace\",
+    \"region_id\": \"$REGION_ID\"
+  }"
+
+```
+
+## Token lifecycle management
+
+### Token expiration
+
+- **Operator Bearer Tokens**: Short-lived, expires after 15 minutes
+- **Scoped Tokens**: Short-lived, expires after 20 minutes
+- **Widget Tokens**: Contain scoped tokens, same lifetime
+
+## Security considerations
+
+### CORS and origin validation
+
+The `allowed_origin` parameter in widget tokens enforces CORS policies:
+
+```javascript
+// Correct origin format
+allowed_origin: "https://yourapp.com"       // ✓ Correct
+allowed_origin: "https://yourapp.com:443"   // ✓ Correct with port
+allowed_origin: "http://localhost:3000"     // ✓ For development
+
+// Incorrect formats
+allowed_origin: "https://yourapp.com/"      // ✗ No trailing slash
+allowed_origin: "yourapp.com"               // ✗ Missing protocol
+allowed_origin: "*.yourapp.com"             // ✗ No wildcards
+
+```
+
+## Error responses
+
+### 401 unauthorized
+
+```json
+{
+  "detail": "Invalid authentication credentials"
+}
+
+```
+
+**Causes:**
+
+- Missing Authorization header
+- Invalid or expired token
+- Wrong token type for endpoint
+
+**Solutions:**
+
+- Verify token is included in Authorization header
+- Ensure using correct token type (operator vs scoped)
+- Generate new token if expired
+
+### 403 forbidden
+
+```json
+{
+  "detail": "Access denied to this resource"
+}
+
+```
+
+**Causes:**
+
+- Scoped token trying to access resources in different workspace
+- Insufficient permissions for operation
+
+**Solutions:**
+
+- Verify token scope matches target workspace
+- Use operator token for organization-level operations
+
+### 422 validation error
+
+```json
+{
+  "detail": [
+    {
+      "loc": ["body", "allowed_origin"],
+      "msg": "field required",
+      "type": "value_error.missing"
+    }
+  ]
+}
+
+```
+
+**Cause:** Missing or invalid request parameters
+
+**Solution:** Verify all required fields are included and properly formatted
+
+## Next steps
+
+- Learn about [Workspace Management](./workspaces.md)
+- Create [Source Templates](./source-templates.md)
+- Create [Connection Templates](./connection-templates.md)
+- Explore [Tag Management](./tags.md) for template organization
diff --git a/docs/ai-agents/embedded/api/configuring-sources.md b/docs/ai-agents/embedded/api/configuring-sources.md
index 5a246ccec8e3..8d60f7f25739 100644
--- a/docs/ai-agents/embedded/api/configuring-sources.md
+++ b/docs/ai-agents/embedded/api/configuring-sources.md
@@ -1,26 +1,34 @@
 ---
+
 products: embedded
+
 ---
 
 # Authentication & Token Management
 
 ## Overview
+
 Airbyte Embedded uses a two-tier authentication system:
+
 1. **Organization-level tokens**: Your main API credentials for managing templates and connections
 2. **User-scoped tokens**: Temporary tokens that allow end-users to configure sources in their isolated workspaces
 
-## Generating User-Scoped Tokens
+For complete authentication documentation including widget tokens and region selection, see [Authentication](./authentication.md).
+
+## Generating user-scoped tokens
 
 When collecting credentials from your users, generate a scoped access token that only has permissions to read and modify integrations in their specific workspace. This follows the principle of least privilege and ensures user data isolation.
 
-This can be done by submitting a request to
+This can be done by submitting a request to:
 
-```
+```bash
 curl --location 'https://api.airbyte.ai/api/v1/embedded/scoped-token' \
+
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer <your_access_token>' \
   --header 'X-Organization-Id: <your_organization_id>' \
   --data '{
+
     "workspace_name": "your_workspace_name",
     "region_id": "optional_region_id"
   }'
@@ -28,59 +36,154 @@ curl --location 'https://api.airbyte.ai/api/v1/embedded/scoped-token' \
 ```
 
 Where:
-- `workspace_name` is a unique identifier within your organization for each customer's tenant.
-- `region_id` is the origin where you're embedding the widget (used for CORS validation). It can be an arbitrary string if you're not using the Embedded Widget.
+
+- `workspace_name` is a unique identifier within your organization for each customer's tenant
+- `region_id` (optional) is the region where the workspace should be created:
+  - US region: `645a183f-b12b-4c6e-8ad3-99e165603450` (default)
+  - EU region: `b9e48d61-f082-4a14-a8d0-799a907938cb`
 
 The API will return a JSON object with a token string:
-```
-{"token":"eyJ0b2tlbiI6ImV5SmhiR2NpT2lKSVV6STFOaUo5LmV5SmhkV1FpT2lKaGFYSmllWFJsTFhObGNuWmxjaUlzSW5OMVlpSTZJbVUyTUdRNE1XRTFMVGt6WkdZdE5HWTVZUzA0TURFekxXSmlZbVkzT1ROalpqQmhNaUlzSW1sdkxtRnBjbUo1ZEdVdVlYVjBhQzUzYjNKcmMzQmhZMlZmYzJOdmNHVWlPbnNpZDI5eWEzTndZV05sU1dRaU9pSm1ZbUU0TVRJeE9DMHpORFkzTFRRMU9EZ3RZVGhrTlMxaE9ETTVObU5rWlRaak1ETWlmU3dpWVdOMElqcDdJbk4xWWlJNkltWmtOR1kzWVdNd0xURmhaREV0TkRJME9DMWlZekZqTFRZNU1HSXdPREk0T1RVNU9TSjlMQ0p5YjJ4bGN5STZXeUpGVFVKRlJFUkZSRjlGVGtSZlZWTkZVaUpkTENKcGMzTWlPaUpvZEhSd2N6b3ZMMk5zYjNWa0xtRnBjbUo1ZEdVdVkyOXRJaXdpZEhsd0lqb2lhVzh1WVdseVlubDBaUzVoZFhSb0xtVnRZbVZrWkdWa1gzWXhJaXdpWlhod0lqb3hOelV6TXpFNE1EVXdmUS4tZ0xJYkQ2OVZ4VUpyajE2QnluSTJhMTJjTDZwU19lVlNTZGxMVGdIbTdFIiwid2lkZ2V0VXJsIjoiaHR0cHM6Ly9jbG91ZC5haXJieXRlLmNvbS9lbWJlZGRlZC13aWRnZXQ/d29ya3NwYWNlSWQ9ZmJhODEyMTgtMzQ2Ny00NTg4LWE4ZDUtYTgzOTZjZGU2YzAzJmFsbG93ZWRPcmlnaW49aHR0cHMlM0ElMkYlMkZhcGkuYWlyYnl0ZS5haSJ9"}
+
+```json
+{
+  "token": "eyJ0b2tlbiI6ImV5SmhiR2NpT2lKSVV6STFOaUo5..."
+}
+
 ```
 
-## Understanding the Token Response
+## Understanding the token response
 
-The response contains:
-- `token`: A JWT token scoped to the user's workspace 
-- `widgetUrl`: A pre-configured URL for the Airbyte Embedded Widget
+The response contains a scoped JWT token that can be used to:
 
-### Using with the Embedded Widget
-Pass the entire response directly to the Airbyte Embedded Widget - no additional processing needed.
+- Create and manage sources in the workspace
+- List available source templates
+- Create connections from sources
 
-### Using with Custom Implementation  
-If building a custom integration, base64 decode the token field to extract the scoped access token:
+### Using the scoped token
+
+Use the token as a Bearer token in subsequent API calls:
+
+```bash
+curl https://api.airbyte.ai/api/v1/embedded/sources \
+
+  -H 'Authorization: Bearer <scoped_token>'
 
-Here's an example decoded token:
-```
-{"token":"eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJhaXJieXRlLXNlcnZlciIsInN1YiI6ImU2MGQ4MWE1LTkzZGYtNGY5YS04MDEzLWJiYmY3OTNjZjBhMiIsImlvLmFpcmJ5dGUuYXV0aC53b3Jrc3BhY2Vfc2NvcGUiOnsid29ya3NwYWNlSWQiOiJmYmE4MTIxOC0zNDY3LTQ1ODgtYThkNS1hODM5NmNkZTZjMDMifSwiYWN0Ijp7InN1YiI6ImZkNGY3YWMwLTFhZDEtNDI0OC1iYzFjLTY5MGIwODI4OTU5OSJ9LCJyb2xlcyI6WyJFTUJFRERFRF9FTkRfVVNFUiJdLCJpc3MiOiJodHRwczovL2Nsb3VkLmFpcmJ5dGUuY29tIiwidHlwIjoiaW8uYWlyYnl0ZS5hdXRoLmVtYmVkZGVkX3YxIiwiZXhwIjoxNzUzMzE4MDUwfQ.-gLIbD69VxUJrj16BynI2a12cL6pS_eVSSdlLTgHm7E","widgetUrl":"https://cloud.airbyte.com/embedded-widget?workspaceId=fba81218-3467-4588-a8d5-a8396cde6c03&allowedOrigin=https%3A%2F%2Fapi.airbyte.ai"}
 ```
 
-You can use the value of this token string as bearer token when creating a source.
+For widget integration, see [Authentication - Widget Token](./authentication.md#widget-token).
 
-# Creating a Source
+## Creating a Source
 
 You'll need 3 pieces of information to create a source for your users:
+
 1. Their workspace ID
 2. The ID of the [Source Template](./source-templates.md) used
 3. The connection configuration
 
+## Basic source creation
+
 Here is an example request:
-```
+
+```bash
 curl --location 'https://api.airbyte.ai/api/v1/embedded/sources' \
+
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer <scoped_token>' \
   --header 'X-Organization-Id: <your_organization_id>' \
   --data '{
+
     "name": "your_source_name",
-    "workspace_id": "your_workspace_id",
+    "workspace ID": "your_workspace ID",
     "source_template_id": "your_source_template_id",
     "source_config": {
       // your source configuration fields here
-    },
-    "selected_connection_template_tags": ["optional_tag1", "optional_tag2"],
-    "selected_connection_template_tags_mode": "any" // or "all"
+    }
   }'
+
 ```
 
 The connection configuration should include all required fields from the connector specification, except for the ones included as default values in your source template.
+
 You can find the full connector specification in the [Connector Registry](https://connectors.airbyte.com/files/registries/v0/cloud_registry.json).
 
 You can find [the reference docs for creating a source here](https://api.airbyte.ai/api/v1/docs#tag/Sources/operation/create_integrations_sources).
+
+## Filtering connection templates with tags
+
+When creating a source, you can control which connection templates are available by using tag filtering:
+
+```bash
+curl --location 'https://api.airbyte.ai/api/v1/embedded/sources' \
+
+  --header 'Content-Type: application/json' \
+  --header 'Authorization: Bearer <scoped_token>' \
+  --header 'X-Organization-Id: <your_organization_id>' \
+  --data '{
+
+    "name": "your_source_name",
+    "workspace ID": "your_workspace ID",
+    "source_template_id": "your_source_template_id",
+    "source_config": {},
+    "selected_connection_template_tags": ["analytics", "standard-sync"],
+    "selected_connection_template_tags_mode": "any"
+  }'
+
+```
+
+**Tag Selection Modes:**
+
+- `any` - Connection template must have at least one of the specified tags
+- `all` - Connection template must have all of the specified tags
+
+This allows you to customize which sync configurations are available based on customer tier, compliance requirements, or other criteria. See [Template Tags](./tags.md) for more information.
+
+## Controlling which streams are synced
+
+Stream selection is configured at the **source template level** using the `customization` field. This allows you to control which streams from a connector are included when connections are created from that template.
+
+### Stream selection modes
+
+There are three stream selection modes available:
+
+- `suggested` (default) - Only sync streams marked as "suggested" by the connector. If no streams are marked as suggested, all streams are synced.
+- `all` - Sync all available streams from the source
+- `whitelist` - Only sync specific streams that you explicitly list
+
+### Whitelisting specific streams
+
+To whitelist specific streams, configure your source template with the `whitelist` mode and provide a list of stream names:
+
+```bash
+curl --location 'https://api.airbyte.ai/api/v1/embedded/templates/sources' \
+  --header 'Content-Type: application/json' \
+  --header 'Authorization: Bearer <your_access_token>' \
+  --header 'X-Organization-Id: <your_organization_id>' \
+  --data '{
+    "name": "PostgreSQL Analytics Template",
+    "actor_definition_id": "decd338e-5647-4c0b-adf4-da0e75f5a750",
+    "partial_default_config": {
+      "ssl_mode": {"mode": "require"}
+    },
+    "customization": {
+      "stream_selection_mode": "whitelist",
+      "stream_whitelist": ["orders", "customers", "products"]
+    }
+  }'
+```
+
+**Important notes:**
+
+- Syncing all streams can cause perceived performance issues depending on the source
+- When using `whitelist` mode, you must provide a non-empty `stream_whitelist` array
+- Stream names must exactly match the stream names provided by the connector
+- When a source is created from this template, only the whitelisted streams will be available for syncing
+- To find available stream names for a connector, use the [discover endpoint](https://api.airbyte.ai/api/v1/docs#tag/Sources/operation/get_source_catalog)
+
+For more information about creating and configuring source templates, see [Source Templates](./source-templates.md).
+
+## Related documentation
+
+- [Source Templates](./source-templates.md) - Create and manage source templates
+- [Connection Templates](./connection-templates.md) - Configure sync behavior
+- [Template Tags](./tags.md) - Organize templates with tags
+- [Authentication](./authentication.md) - Token generation and management
diff --git a/docs/ai-agents/embedded/api/connection-templates.md b/docs/ai-agents/embedded/api/connection-templates.md
index 9ae657258f08..ca3b575343a1 100644
--- a/docs/ai-agents/embedded/api/connection-templates.md
+++ b/docs/ai-agents/embedded/api/connection-templates.md
@@ -1,32 +1,38 @@
 ---
+
 products: embedded
+
 ---
 
 # Connection Templates
 
+A *connection template* pre-defines the **destination side** of every pipeline your customers spin up through the API or Embedded Widget. It answers two questions up-front:
 
-A *connection template* pre-defines the **Destination side** of every pipeline your customers spin up through the Embedded widget. It answers two questions up-front:
-
-1. Where should the data land?  
+1. Where should the data land?
 2. How often should it sync?
 
-When a customer finishes configuring a Source, Airbyte automatically creates the connection by combining their source settings with *your* template.
+When a customer finishes configuring a source, Airbyte automatically creates the connection by combining their source settings with *your* template.
 
+## Creating connection templates
 
 You'll need the following to create a connection template:
+
 - Your organization ID
 - The destination definition ID
 - The destination configuration
 - The destination name: We'll automatically create a destination with the given name in your user's workspaces
-- (optional) A cron expression describing when to run syncs. The cron expression must follow the Quartz syntax. You can use [freeformatter.com](https://www.freeformatter.com/cron-expression-generator-quartz.html) to help validate the expression
+- (Optional) A cron expression describing when to run syncs. The cron expression must follow the Quartz syntax. You can use [freeformatter.com](https://www.freeformatter.com/cron-expression-generator-quartz.html) to help validate the expression
+- (Optional) Tags to organize and filter templates
 
+### Example request
 
-Here is an example request for creating a connection template:
-```
+```bash
 curl --request POST 'https://api.airbyte.ai/api/v1/integrations/templates/connections' \
+
   --header "Content-Type: application/json" \
   --header "Authorization: Bearer <bearer_token>" \
   --data-raw '{
+
     "organization_id": "<organization_id>",
     "destination_name": "string",
     "destination_definition_id": "<destination_definition_id>",
@@ -44,10 +50,12 @@ curl --request POST 'https://api.airbyte.ai/api/v1/integrations/templates/connec
         "flattening": "Root level flattening"
       }
     },
-    "cron_expression": "string",
-    "non_breaking_changes_preference": "ignore",
-    "sync_on_create": true
+    "cron_expression": "0 0 12 * * ?",
+    "non_breaking_changes_preference": "propagate_columns",
+    "sync_on_create": true,
+    "tags": ["analytics", "standard-sync"]
   }'
+
 ```
 
 You can find the full connector specification in the [Connector Registry](https://connectors.airbyte.com/files/registries/v0/cloud_registry.json).
@@ -55,3 +63,287 @@ You can find the full connector specification in the [Connector Registry](https:
 Alternatively, if you want to view the full JSON for a given connector when creating a source or destination from scratch in Airbyte Cloud. After configuring the connector to your desired specifications (partially complete if you want an end user to complete the rest), you can select "Copy JSON". This will give you necessary details like the configuration and the `destination_definition_id`.
 
 You can find [the reference docs for creating a connection template here](https://api.airbyte.ai/api/v1/docs#tag/Template-Connections/operation/create_integrations_templates_connections).
+
+## Configuration options
+
+### sync_on_create
+
+Controls whether the connection should automatically start syncing immediately after creation.
+
+- `true` (default) - Connection starts syncing as soon as it's created
+- `false` - Connection is created but won't sync until its scheduled time or a manual trigger
+
+**Example:**
+
+```json
+{
+  "sync_on_create": false
+}
+
+```
+
+Use `sync_on_create: false` when you want users to review the connection configuration before the first sync runs.
+
+### non_breaking_changes_preference
+
+Controls how Airbyte handles non-breaking schema changes (for example, new columns added to a table).
+
+**Available Options:**
+
+| Value | Behavior |
+|-------|----------|
+| `ignore` | Ignore schema changes; continue syncing only previously configured columns |
+| `disable` | Disable the connection when schema changes are detected |
+| `propagate_columns` | Automatically add new columns to the sync but don't update data types |
+| `propagate_fully` | Automatically propagate all schema changes including column additions and data type updates |
+
+**Example:**
+
+```json
+{
+  "non_breaking_changes_preference": "propagate_columns"
+}
+
+```
+
+**Use Cases:**
+
+- **`ignore`**: Use when you have strict schema requirements and don't want unexpected columns
+- **`disable`**: Use when schema changes require manual review
+- **`propagate_columns`**: Best for most use cases; adds new columns automatically
+- **`propagate_fully`**: Use when you want complete automation of schema evolution
+
+### Cron expression validation
+
+Airbyte provides an endpoint to validate and describe cron expressions:
+
+```bash
+curl -X POST https://api.airbyte.ai/api/v1/integrations/templates/connections/cron/describe \
+
+  -H 'Authorization: Bearer <token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+
+    "cron_expression": "0 0 12 * * ?"
+  }'
+
+```
+
+This endpoint returns a human-readable description of when the cron will execute.
+
+## Managing connection templates
+
+### List connection templates
+
+```bash
+curl 'https://api.airbyte.ai/api/v1/integrations/templates/connections' \
+
+  -H 'Authorization: Bearer <token>'
+
+```
+
+### Filter by tags
+
+You can filter connection templates by tags:
+
+```bash
+curl 'https://api.airbyte.ai/api/v1/integrations/templates/connections?tags=analytics&tags=standard-sync&tags_mode=all' \
+
+  -H 'Authorization: Bearer <token>'
+
+```
+
+**Tag Selection Modes:**
+
+- `any` - Template must have at least one of the specified tags
+- `all` - Template must have all of the specified tags
+
+### Get connection template
+
+```bash
+curl 'https://api.airbyte.ai/api/v1/integrations/templates/connections/{id}' \
+
+  -H 'Authorization: Bearer <token>'
+
+```
+
+### Update connection template
+
+Use the PATCH endpoint to update an existing connection template:
+
+```bash
+curl -X PATCH 'https://api.airbyte.ai/api/v1/integrations/templates/connections/{id}' \
+
+  -H 'Authorization: Bearer <token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+
+    "cron_expression": "0 0 6 * * ?",
+    "non_breaking_changes_preference": "propagate_fully"
+  }'
+
+```
+
+### Delete connection template
+
+```bash
+curl -X DELETE 'https://api.airbyte.ai/api/v1/integrations/templates/connections/{id}' \
+
+  -H 'Authorization: Bearer <token>'
+
+```
+
+## Managing template tags
+
+### Add tag to connection template
+
+```bash
+curl -X POST https://api.airbyte.ai/api/v1/integrations/templates/connections/{id}/tags \
+
+  -H 'Authorization: Bearer <token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+
+    "tag": "premium-features"
+  }'
+
+```
+
+### Remove tag from connection template
+
+```bash
+curl -X DELETE https://api.airbyte.ai/api/v1/integrations/templates/connections/{id}/tags/{tag_name} \
+
+  -H 'Authorization: Bearer <token>'
+
+```
+
+For complete tag management documentation, see [Template Tags](./tags.md).
+
+## Using connection templates with sources
+
+When a user creates a source from a source template, Airbyte automatically:
+
+1. Creates the destination configured in your connection template
+2. Creates a connection between the source and destination
+3. Applies the schedule (cron expression) to the connection
+4. Applies the schema change preference
+5. Starts syncing if `sync_on_create` is `true`
+
+### Filter connection templates by tags
+
+You can control which connection templates are available when creating sources by using tag filtering in widget tokens or scoped tokens:
+
+```bash
+curl -X POST https://api.airbyte.ai/api/v1/embedded/widget-token \
+
+  -H 'Authorization: Bearer <operator_token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+
+    "workspace_name": "customer_workspace",
+    "allowed_origin": "https://yourapp.com",
+    "selected_connection_template_tags": ["standard-sync"],
+    "selected_connection_template_tags_mode": "any"
+  }'
+
+```
+
+This ensures that only connection templates tagged with "standard-sync" are available when the user creates a source.
+
+## Common patterns
+
+### Multi-tenant destinations
+
+Create separate connection templates for different customer tiers:
+
+**Free tier - Basic S3 sync:**
+
+```json
+{
+  "destination_name": "Free Tier S3",
+  "destination_definition_id": "s3-definition-id",
+  "destination_config": {
+    "s3_bucket_name": "free-tier-bucket",
+    "format": { "format_type": "CSV" }
+  },
+  "cron_expression": "0 0 12 * * ?",
+  "non_breaking_changes_preference": "ignore",
+  "tags": ["free-tier"]
+}
+
+```
+
+**Enterprise tier - Optimized BigQuery sync:**
+
+```json
+{
+  "destination_name": "Enterprise BigQuery",
+  "destination_definition_id": "bigquery-definition-id",
+  "destination_config": {
+    "project_id": "enterprise-project",
+    "dataset_id": "enterprise_data"
+  },
+  "cron_expression": "0 */4 * * * ?",
+  "non_breaking_changes_preference": "propagate_fully",
+  "sync_on_create": true,
+  "tags": ["enterprise"]
+}
+
+```
+
+### Testing vs production
+
+Create separate templates for different environments:
+
+```bash
+# Development template - hourly syncs
+{
+  "destination_name": "Dev Database",
+  "cron_expression": "0 0 * * * ?",
+  "tags": ["development", "testing"]
+}
+
+# Production template - daily syncs
+{
+  "destination_name": "Prod Database",
+  "cron_expression": "0 0 2 * * ?",
+  "tags": ["production"]
+}
+
+```
+
+### Compliance-based templates
+
+Create templates for different compliance requirements:
+
+```bash
+# HIPAA-compliant template
+{
+  "destination_name": "HIPAA Compliant Warehouse",
+  "destination_definition_id": "snowflake-definition-id",
+  "destination_config": {
+    "encryption": "enabled",
+    "region": "us-west-2"
+  },
+  "tags": ["hipaa-compliant", "healthcare"]
+}
+
+# GDPR-compliant template
+{
+  "destination_name": "GDPR Compliant Warehouse",
+  "destination_definition_id": "bigquery-definition-id",
+  "destination_config": {
+    "region": "europe-west1"
+  },
+  "tags": ["gdpr-compliant", "eu-region"]
+}
+
+```
+
+## Related documentation
+
+- [Template Tags](./tags.md) - Organize and filter templates with tags
+- [Source Templates](./source-templates.md) - Configure which sources are available
+- [Authentication](./authentication.md) - Generate tokens with template filtering
+- [Configuring Sources](./configuring-sources.md) - How sources and connections work together
diff --git a/docs/ai-agents/embedded/api/source-templates.md b/docs/ai-agents/embedded/api/source-templates.md
index a6e127a354ff..929fa4cc6e9b 100644
--- a/docs/ai-agents/embedded/api/source-templates.md
+++ b/docs/ai-agents/embedded/api/source-templates.md
@@ -1,41 +1,141 @@
 ---
+
 products: embedded
+
 ---
 
 # Source Templates
 
-A source template controls which connectors appear in the Embedded widget and how their config screens look. When a customer opens the widget, only the sources backed by a template are selectable—so you can pre‑set sensible defaults or restrict advanced settings.
+A source template controls which connectors appear in the Embedded widget and how their config screens look. When a customer opens the widget, only the sources backed by a template are selectable, so you can pre-set sensible defaults or restrict advanced settings.
 
-The Airbyte platform comes with ready to use templates. You can also create templates specific to your organization if you need access to more integrations or if you want different default values.
+The Airbyte platform comes with ready-to-use templates. You can also create templates specific to your organization if you need access to more integrations or if you want different default values.
 
-Here is an example request to create a new template using only default values
-```
+## Creating source templates
+
+Here is an example request to create a new template using only default values:
+
+```bash
 curl https://api.airbyte.ai/api/v1/integrations/templates/sources \
--H 'authorization: Bearer <token>' \
--H 'content-type: application/json' \
---data-raw '{
-  "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
-  "actor_definition_id": "45b7d7e6-d7d5-4f31-8c1a-9fd96ce6ee35",
-  "partial_default_config": {}
-}' -vvv
+
+  -H 'Authorization: Bearer <token>' \
+  -H 'Content-Type: application/json' \
+  --data-raw '{
+
+    "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
+    "actor_definition_id": "45b7d7e6-d7d5-4f31-8c1a-9fd96ce6ee35",
+    "partial_default_config": {}
+  }'
+
 ```
 
 You can find the actor definition ID from the [Connector Registry](https://connectors.airbyte.com/files/registries/v0/cloud_registry.json).
 
-The partial_default_config is a JSON object representing keys from the connector spec for which you want to set default values so your users don't need to set them up themselves.
+The `partial_default_config` is a JSON object representing keys from the connector spec for which you want to set default values so your users don't need to set them up themselves.
+
+### Optional: add tags during creation
+
+You can also add tags to organize and filter templates:
+
+```bash
+curl https://api.airbyte.ai/api/v1/integrations/templates/sources \
+
+  -H 'Authorization: Bearer <token>' \
+  -H 'Content-Type: application/json' \
+  --data-raw '{
 
-# Deleting Templates
- 
-You can delete Source Templates by submitting a DELETE request to the API:
+    "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
+    "actor_definition_id": "45b7d7e6-d7d5-4f31-8c1a-9fd96ce6ee35",
+    "partial_default_config": {},
+    "tags": ["crm", "pro-tier"]
+  }'
 
 ```
-curl -X DELETE 'https://api.airbyte.ai/api/v1/integrations/templates/sources/{id}' \
--H 'authorization: Bearer <token>'
+
+See [Template Tags](./tags.md) for more information on organizing templates with tags.
+
+## Updating source templates
+
+You can update an existing source template using the PATCH endpoint:
+
+```bash
+curl -X PATCH https://api.airbyte.ai/api/v1/integrations/templates/sources/{id} \
+
+  -H 'Authorization: Bearer <token>' \
+  -H 'Content-Type: application/json' \
+  --data-raw '{
+
+    "partial_default_config": {
+      "api_key": "new_default_value"
+    }
+  }'
+
 ```
 
-Sources created from a deleted Source Template will stop showing up in the Widget.
+When a source template is updated, all existing sources created from it will also be updated.
 
-When a Source Template is updated, all existing Sources created from it will also be updated.
+## Listing templates
 
-# Listing Templates
 The [List Source Templates endpoint](https://api.airbyte.ai/api/v1/docs#tag/Template-Sources/operation/list_integrations_templates_sources) lists both the templates you created, as well as standard templates that are available to everyone using the platform.
+
+### Filter by tags
+
+You can filter source templates by tags:
+
+```bash
+curl 'https://api.airbyte.ai/api/v1/integrations/templates/sources?tags=crm&tags=sales&tags_mode=any' \
+
+  -H 'Authorization: Bearer <token>'
+
+```
+
+**Tag Selection Modes:**
+
+- `any` - Template must have at least one of the specified tags
+- `all` - Template must have all of the specified tags
+
+## Deleting templates
+
+You can delete source templates by submitting a DELETE request to the API:
+
+```bash
+curl -X DELETE 'https://api.airbyte.ai/api/v1/integrations/templates/sources/{id}' \
+
+  -H 'Authorization: Bearer <token>'
+
+```
+
+Sources created from a deleted source template will stop showing up in the widget.
+
+## Managing template tags
+
+### Add tag to source template
+
+```bash
+curl -X POST https://api.airbyte.ai/api/v1/integrations/templates/sources/{id}/tags \
+
+  -H 'Authorization: Bearer <token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+
+    "tag": "pro-tier"
+  }'
+
+```
+
+### Remove tag from source template
+
+```bash
+curl -X DELETE https://api.airbyte.ai/api/v1/integrations/templates/sources/{id}/tags/{tag_name} \
+
+  -H 'Authorization: Bearer <token>'
+
+```
+
+For complete tag management documentation, see [Template Tags](./tags.md).
+
+## Related documentation
+
+- [Template Tags](./tags.md) - Organize and filter templates with tags
+- [Configuring Sources](./configuring-sources.md) - Create sources from templates
+- [Connection Templates](./connection-templates.md) - Configure sync behavior
+- [Authentication](./authentication.md) - Generate tokens for API access
diff --git a/docs/ai-agents/embedded/api/tags.md b/docs/ai-agents/embedded/api/tags.md
new file mode 100644
index 000000000000..8fbde5b11828
--- /dev/null
+++ b/docs/ai-agents/embedded/api/tags.md
@@ -0,0 +1,845 @@
+# Template Tags
+
+Template tags provide a flexible way to organize, categorize, and filter both source templates and connection templates. Tags enable you to control which templates are available to different users, implement tier-based access, and organize templates by use case, industry, or any custom criteria.
+
+## Overview
+
+The Template Tags API allows you to:
+
+- **Create and manage tags** centrally for your organization
+- **Tag source templates** to control which data sources are available
+- **Tag connection templates** to control sync configurations
+- **Filter templates by tags** when generating widget tokens or listing templates
+- **Implement access control** using tag-based filtering
+
+## Use cases
+
+### Tier-based access control
+
+Implement different feature tiers by tagging templates:
+
+```bash
+Tags: "free-tier", "pro-tier", "enterprise"
+
+Example:
+
+- Basic connectors: tagged with "free-tier"
+- Advanced connectors: tagged with "pro-tier"
+- Premium connectors: tagged with "enterprise"
+
+```
+
+### Industry-specific organization
+
+Organize templates by industry or compliance requirements:
+
+```bash
+Tags: "healthcare", "hipaa-compliant", "finance", "retail"
+
+Example:
+
+- HIPAA-compliant connectors: tagged with "healthcare", "hipaa-compliant"
+- Financial connectors: tagged with "finance", "pci-compliant"
+
+```
+
+### Feature staging
+
+Manage connector rollout with stability tags:
+
+```bash
+Tags: "stable", "beta", "experimental"
+
+Example:
+
+- Production-ready: tagged with "stable"
+- Beta features: tagged with "beta"
+- Experimental features: tagged with "experimental"
+
+```
+
+### Use-case categorization
+
+Group templates by business function:
+
+```bash
+Tags: "crm", "analytics", "marketing", "sales", "support"
+
+Example:
+
+- Salesforce, HubSpot: tagged with "crm", "sales"
+- Google Analytics, Mixpanel: tagged with "analytics"
+
+```
+
+## Tag selection modes
+
+When filtering templates by tags, you can control matching behavior with **Tag Selection Modes**:
+
+| Mode | Behavior | Example |
+|------|----------|---------|
+| `any` | Template must have **at least one** of the specified tags | Tags: `["crm", "sales"]` matches templates with "crm" OR "sales" |
+| `all` | Template must have **all** of the specified tags | Tags: `["crm", "sales"]` matches only templates with both "crm" AND "sales" |
+
+## Tag management API
+
+### Create tag
+
+Create a new tag for your organization.
+
+#### Endpoint
+
+```bash
+POST https://api.airbyte.ai/api/v1/integrations/templates/tags
+
+```
+
+#### Authentication
+
+Requires **Operator Bearer Token** or **Scoped Token**
+
+#### Request body
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Tag name (max 255 characters) |
+
+#### Request example
+
+```bash
+curl -X POST https://api.airbyte.ai/api/v1/integrations/templates/tags \
+
+  -H 'Authorization: Bearer <your_operator_token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+
+    "name": "pro-tier"
+  }'
+
+```
+
+#### Response example
+
+```json
+{
+  "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
+  "name": "pro-tier",
+  "organization_id": "12345678-1234-1234-1234-123456789012",
+  "created_at": "2025-10-08T10:30:00Z",
+  "updated_at": "2025-10-08T10:30:00Z"
+}
+
+```
+
+### List tags
+
+Retrieve all tags for your organization.
+
+#### Endpoint
+
+```bash
+GET https://api.airbyte.ai/api/v1/integrations/templates/tags
+
+```
+
+#### Authentication
+
+Requires **Operator Bearer Token** or **Scoped Token**
+
+#### Request example
+
+```bash
+curl https://api.airbyte.ai/api/v1/integrations/templates/tags \
+
+  -H 'Authorization: Bearer <your_operator_token>'
+
+```
+
+#### Response example
+
+```json
+{
+  "data": [
+    {
+      "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
+      "name": "free-tier",
+      "organization_id": "12345678-1234-1234-1234-123456789012",
+      "created_at": "2025-10-01T10:00:00Z",
+      "updated_at": "2025-10-01T10:00:00Z"
+    },
+    {
+      "id": "b2c3d4e5-f6g7-8901-bc23-de45fg678901",
+      "name": "pro-tier",
+      "organization_id": "12345678-1234-1234-1234-123456789012",
+      "created_at": "2025-10-05T14:20:00Z",
+      "updated_at": "2025-10-05T14:20:00Z"
+    },
+    {
+      "id": "c3d4e5f6-g7h8-9012-cd34-ef56gh789012",
+      "name": "healthcare",
+      "organization_id": "12345678-1234-1234-1234-123456789012",
+      "created_at": "2025-10-07T09:15:00Z",
+      "updated_at": "2025-10-07T09:15:00Z"
+    }
+  ]
+}
+
+```
+
+### Update tag
+
+Update an existing tag's name.
+
+#### Endpoint
+
+```bash
+PUT https://api.airbyte.ai/api/v1/integrations/templates/tags/{name}
+
+```
+
+#### Authentication
+
+Requires **Operator Bearer Token** or **Scoped Token**
+
+#### Path parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | Current name of the tag |
+
+#### Request body
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | New name for the tag (max 255 characters) |
+
+#### Request example
+
+```bash
+curl -X PUT https://api.airbyte.ai/api/v1/integrations/templates/tags/pro-tier \
+
+  -H 'Authorization: Bearer <your_operator_token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+
+    "name": "professional-tier"
+  }'
+
+```
+
+#### Response example
+
+```json
+{
+  "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
+  "name": "professional-tier",
+  "organization_id": "12345678-1234-1234-1234-123456789012",
+  "created_at": "2025-10-08T10:30:00Z",
+  "updated_at": "2025-10-08T16:45:00Z"
+}
+
+```
+
+#### Important notes
+
+- Updating a tag name automatically updates all associations with source and connection templates
+- The tag name is used as the identifier in the URL path parameter
+
+### Delete tag
+
+Delete a tag from your organization.
+
+#### Endpoint
+
+```bash
+DELETE https://api.airbyte.ai/api/v1/integrations/templates/tags/{name}
+
+```
+
+#### Authentication
+
+Requires **Operator Bearer Token** or **Scoped Token**
+
+#### Path parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | Name of the tag to delete |
+
+#### Request example
+
+```bash
+curl -X DELETE https://api.airbyte.ai/api/v1/integrations/templates/tags/experimental \
+
+  -H 'Authorization: Bearer <your_operator_token>'
+
+```
+
+#### Response example
+
+```json
+{
+  "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
+  "deleted_at": "2025-10-08T17:00:00Z"
+}
+
+```
+
+#### Important notes
+
+- Deleting a tag removes all associations with source and connection templates
+- This operation cannot be undone
+- Templates will remain but will no longer have this tag
+
+## Tagging source templates
+
+### Add tag to source template
+
+Add a tag to a specific source template.
+
+#### Endpoint
+
+```bash
+POST https://api.airbyte.ai/api/v1/integrations/templates/sources/{id}/tags
+
+```
+
+#### Authentication
+
+Requires **Operator Bearer Token** or **Scoped Token**
+
+#### Path parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | UUID | Yes | Source template ID |
+
+#### Request body
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `tag` | string | Yes | Name of the tag to add |
+
+#### Request example
+
+```bash
+curl -X POST https://api.airbyte.ai/api/v1/integrations/templates/sources/a1b2c3d4-e5f6-7890-ab12-cd34ef567890/tags \
+
+  -H 'Authorization: Bearer <your_operator_token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+
+    "tag": "pro-tier"
+  }'
+
+```
+
+#### Response example
+
+```json
+{
+  "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
+  "name": "Salesforce Source",
+  "actor_definition_id": "def123-...",
+  "organization_id": "12345678-1234-1234-1234-123456789012",
+  "tags": ["crm", "sales", "pro-tier"],
+  "created_at": "2025-10-01T10:00:00Z",
+  "updated_at": "2025-10-08T17:15:00Z"
+}
+
+```
+
+### Remove tag from source template
+
+Remove a tag from a specific source template.
+
+#### Endpoint
+
+```bash
+DELETE https://api.airbyte.ai/api/v1/integrations/templates/sources/{id}/tags/{tag_name}
+
+```
+
+#### Authentication
+
+Requires **Operator Bearer Token** or **Scoped Token**
+
+#### Path parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | UUID | Yes | Source template ID |
+| `tag_name` | string | Yes | Name of the tag to remove |
+
+#### Request example
+
+```bash
+curl -X DELETE https://api.airbyte.ai/api/v1/integrations/templates/sources/a1b2c3d4-e5f6-7890-ab12-cd34ef567890/tags/beta \
+
+  -H 'Authorization: Bearer <your_operator_token>'
+
+```
+
+#### Response example
+
+```json
+{
+  "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
+  "name": "Salesforce Source",
+  "actor_definition_id": "def123-...",
+  "organization_id": "12345678-1234-1234-1234-123456789012",
+  "tags": ["crm", "sales", "pro-tier"],
+  "created_at": "2025-10-01T10:00:00Z",
+  "updated_at": "2025-10-08T17:20:00Z"
+}
+
+```
+
+## Tagging connection templates
+
+### Add tag to connection template
+
+Add a tag to a specific connection template.
+
+#### Endpoint
+
+```bash
+POST https://api.airbyte.ai/api/v1/integrations/templates/connections/{id}/tags
+
+```
+
+#### Authentication
+
+Requires **Operator Bearer Token**
+
+#### Path parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | UUID | Yes | Connection template ID |
+
+#### Request body
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `tag` | string | Yes | Name of the tag to add |
+
+#### Request example
+
+```bash
+curl -X POST https://api.airbyte.ai/api/v1/integrations/templates/connections/b2c3d4e5-f6g7-8901-bc23-de45fg678901/tags \
+
+  -H 'Authorization: Bearer <your_operator_token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+
+    "tag": "standard-sync"
+  }'
+
+```
+
+#### Response example
+
+```json
+{
+  "id": "b2c3d4e5-f6g7-8901-bc23-de45fg678901",
+  "name": "Standard BigQuery Sync",
+  "destination_actor_definition_id": "dest456-...",
+  "organization_id": "12345678-1234-1234-1234-123456789012",
+  "tags": ["analytics", "standard-sync"],
+  "created_at": "2025-10-02T11:00:00Z",
+  "updated_at": "2025-10-08T17:25:00Z"
+}
+
+```
+
+### Remove tag from connection template
+
+Remove a tag from a specific connection template.
+
+#### Endpoint
+
+```bash
+DELETE https://api.airbyte.ai/api/v1/integrations/templates/connections/{id}/tags/{tag_name}
+
+```
+
+#### Authentication
+
+Requires **Operator Bearer Token**
+
+#### Path parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | UUID | Yes | Connection template ID |
+| `tag_name` | string | Yes | Name of the tag to remove |
+
+#### Request example
+
+```bash
+curl -X DELETE https://api.airbyte.ai/api/v1/integrations/templates/connections/b2c3d4e5-f6g7-8901-bc23-de45fg678901/tags/beta \
+
+  -H 'Authorization: Bearer <your_operator_token>'
+
+```
+
+#### Response example
+
+```json
+{
+  "id": "b2c3d4e5-f6g7-8901-bc23-de45fg678901",
+  "name": "Standard BigQuery Sync",
+  "destination_actor_definition_id": "dest456-...",
+  "organization_id": "12345678-1234-1234-1234-123456789012",
+  "tags": ["analytics", "standard-sync"],
+  "created_at": "2025-10-02T11:00:00Z",
+  "updated_at": "2025-10-08T17:30:00Z"
+}
+
+```
+
+## Filtering templates by tags
+
+### Widget token with tag filtering
+
+When generating a widget token, you can filter which templates are available by specifying tags:
+
+```bash
+curl -X POST https://api.airbyte.ai/api/v1/embedded/widget-token \
+
+  -H 'Authorization: Bearer <your_operator_token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+
+    "workspace_name": "customer_workspace",
+    "allowed_origin": "https://yourapp.com",
+    "selected_source_template_tags": ["pro-tier", "enterprise"],
+    "selected_source_template_tags_mode": "any",
+    "selected_connection_template_tags": ["standard-sync"],
+    "selected_connection_template_tags_mode": "all"
+  }'
+
+```
+
+In this example:
+
+- **Source templates**: Must have "pro-tier" OR "enterprise" tag (`any` mode)
+- **Connection templates**: Must have "standard-sync" tag (`all` mode with single tag)
+
+### List templates with tag filtering
+
+Both source and connection template list endpoints support tag filtering:
+
+**Source templates:**
+
+```bash
+curl https://api.airbyte.ai/api/v1/integrations/templates/sources?tags=crm&tags=sales&tags_mode=any \
+
+  -H 'Authorization: Bearer <your_operator_token>'
+
+```
+
+**Connection templates:**
+
+```bash
+curl https://api.airbyte.ai/api/v1/integrations/templates/connections?tags=analytics&tags=standard-sync&tags_mode=all \
+
+  -H 'Authorization: Bearer <your_operator_token>'
+
+```
+
+## Common workflows
+
+### Workflow 1: set up tier-based access
+
+```bash
+# 1. Create tier tags
+curl -X POST https://api.airbyte.ai/api/v1/integrations/templates/tags \
+
+  -H "Authorization: Bearer $OPERATOR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "free-tier"}'
+
+curl -X POST https://api.airbyte.ai/api/v1/integrations/templates/tags \
+
+  -H "Authorization: Bearer $OPERATOR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "pro-tier"}'
+
+curl -X POST https://api.airbyte.ai/api/v1/integrations/templates/tags \
+
+  -H "Authorization: Bearer $OPERATOR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "enterprise"}'
+
+# 2. Tag source templates
+curl -X POST https://api.airbyte.ai/api/v1/integrations/templates/sources/$BASIC_SOURCE_ID/tags \
+
+  -H "Authorization: Bearer $OPERATOR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"tag": "free-tier"}'
+
+curl -X POST https://api.airbyte.ai/api/v1/integrations/templates/sources/$PREMIUM_SOURCE_ID/tags \
+
+  -H "Authorization: Bearer $OPERATOR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"tag": "enterprise"}'
+
+# 3. Generate widget tokens with tier filtering
+# Free tier customer
+curl -X POST https://api.airbyte.ai/api/v1/embedded/widget-token \
+
+  -H "Authorization: Bearer $OPERATOR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+
+    "workspace_name": "free_customer",
+    "allowed_origin": "https://yourapp.com",
+    "selected_source_template_tags": ["free-tier"],
+    "selected_source_template_tags_mode": "any"
+  }'
+
+# Enterprise tier customer
+curl -X POST https://api.airbyte.ai/api/v1/embedded/widget-token \
+
+  -H "Authorization: Bearer $OPERATOR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+
+    "workspace_name": "enterprise_customer",
+    "allowed_origin": "https://yourapp.com",
+    "selected_source_template_tags": ["free-tier", "pro-tier", "enterprise"],
+    "selected_source_template_tags_mode": "any"
+  }'
+
+```
+
+### Workflow 2: organize by industry
+
+```bash
+# 1. Create industry tags
+for industry in "healthcare" "finance" "retail" "technology"; do
+  curl -X POST https://api.airbyte.ai/api/v1/integrations/templates/tags \
+
+    -H "Authorization: Bearer $OPERATOR_TOKEN" \
+    -H "Content-Type: application/json" \
+    -d "{\"name\": \"$industry\"}"
+
+done
+
+# 2. Tag healthcare-specific templates
+curl -X POST https://api.airbyte.ai/api/v1/integrations/templates/sources/$EMR_SOURCE_ID/tags \
+
+  -H "Authorization: Bearer $OPERATOR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"tag": "healthcare"}'
+
+# 3. Also tag with compliance tags
+curl -X POST https://api.airbyte.ai/api/v1/integrations/templates/tags \
+
+  -H "Authorization: Bearer $OPERATOR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "hipaa-compliant"}'
+
+curl -X POST https://api.airbyte.ai/api/v1/integrations/templates/sources/$EMR_SOURCE_ID/tags \
+
+  -H "Authorization: Bearer $OPERATOR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"tag": "hipaa-compliant"}'
+
+# 4. Filter for healthcare customer with compliance requirements
+curl -X POST https://api.airbyte.ai/api/v1/embedded/widget-token \
+
+  -H "Authorization: Bearer $OPERATOR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+
+    "workspace_name": "healthcare_customer",
+    "allowed_origin": "https://yourapp.com",
+    "selected_source_template_tags": ["healthcare", "hipaa-compliant"],
+    "selected_source_template_tags_mode": "all"
+  }'
+
+```
+
+### Workflow 3: feature staging
+
+```bash
+# 1. Create stability tags
+curl -X POST https://api.airbyte.ai/api/v1/integrations/templates/tags \
+
+  -H "Authorization: Bearer $OPERATOR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "stable"}'
+
+curl -X POST https://api.airbyte.ai/api/v1/integrations/templates/tags \
+
+  -H "Authorization: Bearer $OPERATOR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "beta"}'
+
+# 2. Tag production-ready templates
+curl -X POST https://api.airbyte.ai/api/v1/integrations/templates/sources/$PROD_SOURCE_ID/tags \
+
+  -H "Authorization: Bearer $OPERATOR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"tag": "stable"}'
+
+# 3. Tag beta features
+curl -X POST https://api.airbyte.ai/api/v1/integrations/templates/sources/$BETA_SOURCE_ID/tags \
+
+  -H "Authorization: Bearer $OPERATOR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"tag": "beta"}'
+
+# 4. Prod customers see only stable
+curl -X POST https://api.airbyte.ai/api/v1/embedded/widget-token \
+
+  -H "Authorization: Bearer $OPERATOR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+
+    "workspace_name": "prod_customer",
+    "allowed_origin": "https://yourapp.com",
+    "selected_source_template_tags": ["stable"],
+    "selected_source_template_tags_mode": "any"
+  }'
+
+# 5. Beta testers see both
+curl -X POST https://api.airbyte.ai/api/v1/embedded/widget-token \
+
+  -H "Authorization: Bearer $OPERATOR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+
+    "workspace_name": "beta_tester",
+    "allowed_origin": "https://yourapp.com",
+    "selected_source_template_tags": ["stable", "beta"],
+    "selected_source_template_tags_mode": "any"
+  }'
+
+```
+
+## Error responses
+
+### 404 tag not found
+
+```json
+{
+  "detail": "Template tag with name 'invalid-tag' not found."
+}
+
+```
+
+**Cause:** Attempting to update or delete a tag that doesn't exist
+
+**Solution:** Verify the tag name and ensure it exists in your organization
+
+### 404 tag not found on template
+
+```json
+{
+  "detail": "Tag 'pro-tier' not found on this template."
+}
+
+```
+
+**Cause:** Attempting to remove a tag that isn't associated with the template
+
+**Solution:** List the template's tags to verify which tags are attached
+
+### 422 validation error
+
+```json
+{
+  "detail": [
+    {
+      "loc": ["body", "name"],
+      "msg": "ensure this value has at most 255 characters",
+      "type": "value_error.any_str.max_length"
+    }
+  ]
+}
+
+```
+
+**Cause:** Tag name exceeds maximum length
+
+**Solution:** Use a tag name with 255 characters or fewer
+
+## Integration examples
+
+### Multi-tenant SaaS with tiered access
+
+```javascript
+// Backend: Generate widget token based on customer tier
+async function generateCustomerWidgetToken(customerId) {
+  const customer = await db.customers.get(customerId);
+
+  // Map customer tier to tags
+  const tierTagsMap = {
+    'free': ['free-tier'],
+    'pro': ['free-tier', 'pro-tier'],
+    'enterprise': ['free-tier', 'pro-tier', 'enterprise']
+  };
+
+  const response = await fetch('https://api.airbyte.ai/api/v1/embedded/widget-token', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${process.env.AIRBYTE_OPERATOR_TOKEN}`,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      workspace_name: `customer_${customerId}`,
+      allowed_origin: 'https://yourapp.com',
+      selected_source_template_tags: tierTagsMap[customer.tier],
+      selected_source_template_tags_mode: 'any'
+    })
+  });
+
+  return await response.json();
+}
+
+```
+
+### Industry-specific applications
+
+```python
+# Backend: Healthcare application with compliance filtering
+def get_compliant_widget_token(customer_id, compliance_requirements):
+    customer = db.customers.get(customer_id)
+
+    # Build tags based on compliance needs
+    tags = ['healthcare']
+
+    if 'HIPAA' in compliance_requirements:
+        tags.append('hipaa-compliant')
+
+    if 'GDPR' in compliance_requirements:
+        tags.append('gdpr-compliant')
+
+    response = requests.post(
+        'https://api.airbyte.ai/api/v1/embedded/widget-token',
+        headers={
+            'Authorization': f'Bearer {OPERATOR_TOKEN}',
+            'Content-Type': 'application/json'
+        },
+        json={
+            'workspace_name': f'customer_{customer_id}',
+            'allowed_origin': 'https://healthcare-app.com',
+            'selected_source_template_tags': tags,
+            'selected_source_template_tags_mode': 'all'  # Must have all compliance tags
+        }
+    )
+
+    return response.json()
+
+```
+
+## Related documentation
+
+- [Authentication](./authentication.md) - Learn about widget tokens and tag filtering
+- [Source Templates](./source-templates.md) - Create and manage source templates
+- [Connection Templates](./connection-templates.md) - Create and manage connection templates
+- [Widget Integration](../widget/README.md) - Embed the Airbyte widget with tag filtering
diff --git a/docs/ai-agents/embedded/api/workspaces.md b/docs/ai-agents/embedded/api/workspaces.md
new file mode 100644
index 000000000000..993db8ef82c2
--- /dev/null
+++ b/docs/ai-agents/embedded/api/workspaces.md
@@ -0,0 +1,461 @@
+# Workspace Management
+
+Workspaces in Airbyte represent logical containers for your data integration pipelines. Each workspace can contain multiple sources, destinations, and connections. The Workspace Management API allows you to programmatically list, retrieve, update, and manage workspaces within your organization.
+
+## Overview
+
+The Workspace API provides comprehensive management capabilities:
+
+- **List workspaces** with filtering and pagination
+- **Get workspace details** by ID
+- **Update workspace** name and status
+- **Delete workspaces** (soft delete)
+- **View workspace statistics** (active/inactive counts)
+- **Sync workspaces** from Airbyte Cloud to your local database
+
+All workspace endpoints require **Operator Bearer Token** authentication.
+
+## Workspace status
+
+Each workspace has a status that controls its availability:
+
+- `active` - Workspace is active and all connections can run normally
+- `inactive` - Workspace is inactive; setting this status automatically disables all active connections
+
+## List workspaces
+
+Retrieve a paginated list of workspaces for your organization.
+
+### Endpoint
+
+```bash
+GET https://api.airbyte.ai/api/v1/workspaces
+
+```
+
+### Query parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `name_contains` | string | No | - | Filter workspaces by name (case-insensitive partial match) |
+| `status` | string | No | - | Filter by status: `active` or `inactive`. Returns all if not specified |
+| `limit` | integer | No | 20 | Maximum number of workspaces to return (max: 100) |
+| `cursor` | string | No | - | Opaque pagination cursor from previous response |
+
+### Request example
+
+```bash
+curl https://api.airbyte.ai/api/v1/workspaces?limit=50&status=active \
+
+  -H 'Authorization: Bearer <your_operator_token>'
+
+```
+
+### Response example
+
+```json
+{
+  "data": [
+    {
+      "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
+      "name": "Production Workspace",
+      "organization_id": "12345678-1234-1234-1234-123456789012",
+      "status": "active",
+      "created_at": "2025-01-15T10:30:00Z",
+      "updated_at": "2025-01-15T10:30:00Z"
+    },
+    {
+      "id": "b2c3d4e5-f6g7-8901-bc23-de45fg678901",
+      "name": "Development Workspace",
+      "organization_id": "12345678-1234-1234-1234-123456789012",
+      "status": "active",
+      "created_at": "2025-01-10T14:20:00Z",
+      "updated_at": "2025-01-12T09:15:00Z"
+    }
+  ],
+  "next": "https://api.airbyte.ai/api/v1/workspaces?limit=50&cursor=eyJvZmZzZXQiOjUwfQ=="
+}
+
+```
+
+### Response fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `data` | array | List of workspace objects |
+| `next` | string | URL for the next page of results (null if no more pages) |
+
+#### Workspace object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Unique identifier for the workspace |
+| `name` | string | Workspace name |
+| `organization_id` | UUID | Organization that owns this workspace |
+| `status` | string | Workspace status: `active` or `inactive` |
+| `created_at` | datetime | Timestamp when the workspace was created |
+| `updated_at` | datetime | Timestamp when the workspace was last updated |
+
+### Pagination
+
+The API uses cursor-based pagination. To retrieve the next page:
+
+1. Check the `next` field in the response
+2. If `next` is not null, make a GET request to that URL
+3. Continue until `next` is null
+
+**Example pagination workflow:**
+
+```bash
+# First page
+curl https://api.airbyte.ai/api/v1/workspaces?limit=20 \
+
+  -H 'Authorization: Bearer <your_token>'
+
+# Use the 'next' URL from the response for the second page
+curl https://api.airbyte.ai/api/v1/workspaces?limit=20&cursor=eyJvZmZzZXQiOjIwfQ== \
+
+  -H 'Authorization: Bearer <your_token>'
+
+```
+
+### Filtering examples
+
+**Filter by name:**
+
+```bash
+curl https://api.airbyte.ai/api/v1/workspaces?name_contains=prod \
+
+  -H 'Authorization: Bearer <your_token>'
+
+```
+
+**Filter by status:**
+
+```bash
+curl https://api.airbyte.ai/api/v1/workspaces?status=active \
+
+  -H 'Authorization: Bearer <your_token>'
+
+```
+
+**Combined filters:**
+
+```bash
+curl https://api.airbyte.ai/api/v1/workspaces?status=active&name_contains=dev&limit=10 \
+
+  -H 'Authorization: Bearer <your_token>'
+
+```
+
+## Get workspace
+
+Retrieve details for a specific workspace.
+
+### Endpoint
+
+```bash
+GET https://api.airbyte.ai/api/v1/workspaces/{workspace ID}
+
+```
+
+### Path parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `workspace ID` | UUID | Yes | Unique identifier of the workspace |
+
+### Request example
+
+```bash
+curl https://api.airbyte.ai/api/v1/workspaces/a1b2c3d4-e5f6-7890-ab12-cd34ef567890 \
+
+  -H 'Authorization: Bearer <your_operator_token>'
+
+```
+
+### Response example
+
+```json
+{
+  "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
+  "name": "Production Workspace",
+  "organization_id": "12345678-1234-1234-1234-123456789012",
+  "status": "active",
+  "created_at": "2025-01-15T10:30:00Z",
+  "updated_at": "2025-01-15T10:30:00Z"
+}
+
+```
+
+## Update workspace
+
+Update a workspace's name and/or status.
+
+### Endpoint
+
+```bash
+PUT https://api.airbyte.ai/api/v1/workspaces/{workspace ID}
+
+```
+
+### Path parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `workspace ID` | UUID | Yes | Unique identifier of the workspace |
+
+### Request body
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | No | New name for the workspace |
+| `status` | string | No | New status: `active` or `inactive` |
+
+### Important behavior
+
+When setting status to `inactive`, **all active connections in the workspace will be automatically disabled**. This ensures that no data syncs occur while the workspace is inactive.
+
+### Request example
+
+**Update workspace name:**
+
+```bash
+curl -X PUT https://api.airbyte.ai/api/v1/workspaces/a1b2c3d4-e5f6-7890-ab12-cd34ef567890 \
+
+  -H 'Authorization: Bearer <your_operator_token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+
+    "name": "Production Workspace - Updated"
+  }'
+
+```
+
+**Change workspace status to inactive:**
+
+```bash
+curl -X PUT https://api.airbyte.ai/api/v1/workspaces/a1b2c3d4-e5f6-7890-ab12-cd34ef567890 \
+
+  -H 'Authorization: Bearer <your_operator_token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+
+    "status": "inactive"
+  }'
+
+```
+
+**Update both name and status:**
+
+```bash
+curl -X PUT https://api.airbyte.ai/api/v1/workspaces/a1b2c3d4-e5f6-7890-ab12-cd34ef567890 \
+
+  -H 'Authorization: Bearer <your_operator_token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+
+    "name": "Archived Production",
+    "status": "inactive"
+  }'
+
+```
+
+### Response example
+
+```json
+{
+  "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
+  "name": "Production Workspace - Updated",
+  "organization_id": "12345678-1234-1234-1234-123456789012",
+  "status": "active",
+  "created_at": "2025-01-15T10:30:00Z",
+  "updated_at": "2025-10-08T15:45:00Z"
+}
+
+```
+
+## Delete workspace
+
+Delete a workspace from both Airbyte Cloud and mark it as deleted locally (soft delete).
+
+### Endpoint
+
+```bash
+DELETE https://api.airbyte.ai/api/v1/workspaces/{workspace ID}
+
+```
+
+### Path parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `workspace ID` | UUID | Yes | Unique identifier of the workspace |
+
+### Request example
+
+```bash
+curl -X DELETE https://api.airbyte.ai/api/v1/workspaces/a1b2c3d4-e5f6-7890-ab12-cd34ef567890 \
+
+  -H 'Authorization: Bearer <your_operator_token>'
+
+```
+
+### Response example
+
+```json
+{
+  "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
+  "deleted_at": "2025-10-08T16:00:00Z"
+}
+
+```
+
+### Important notes
+
+- This performs a soft delete in the local database
+- The workspace is deleted from Airbyte Cloud
+- All associated resources (sources, destinations, connections) will also be deleted
+
+## Get workspace statistics
+
+Retrieve statistics about workspaces in your organization.
+
+### Endpoint
+
+```bash
+GET https://api.airbyte.ai/api/v1/workspaces/stats
+
+```
+
+### Request example
+
+```bash
+curl https://api.airbyte.ai/api/v1/workspaces/stats \
+
+  -H 'Authorization: Bearer <your_operator_token>'
+
+```
+
+### Response example
+
+```json
+{
+  "active_count": 12,
+  "inactive_count": 3,
+  "total_count": 15
+}
+
+```
+
+### Response fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `active_count` | integer | Number of workspaces with status `active` |
+| `inactive_count` | integer | Number of workspaces with status `inactive` |
+| `total_count` | integer | Total number of workspaces |
+
+### Response fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `total_count` | integer | Total number of workspaces found in Airbyte Cloud |
+| `created_count` | integer | Number of new workspaces created locally |
+| `created_workspace IDs` | array of UUIDs | IDs of the newly created workspaces |
+
+## Common use cases
+
+### Monitor workspace health
+
+Combine workspace stats and listing to monitor your organization:
+
+```bash
+# Get overview statistics
+curl https://api.airbyte.ai/api/v1/workspaces/stats \
+
+  -H 'Authorization: Bearer <your_token>'
+
+# List inactive workspaces for review
+curl https://api.airbyte.ai/api/v1/workspaces?status=inactive \
+
+  -H 'Authorization: Bearer <your_token>'
+
+```
+
+### Deactivate workspace and connections
+
+When you need to pause all activity in a workspace:
+
+```bash
+curl -X PUT https://api.airbyte.ai/api/v1/workspaces/a1b2c3d4-e5f6-7890-ab12-cd34ef567890 \
+
+  -H 'Authorization: Bearer <your_token>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+
+    "status": "inactive"
+  }'
+
+```
+
+This automatically disables all connections, preventing any data syncs.
+
+### Search for workspaces
+
+Find workspaces by name pattern:
+
+```bash
+# Find all production workspaces
+curl https://api.airbyte.ai/api/v1/workspaces?name_contains=production \
+
+  -H 'Authorization: Bearer <your_token>'
+
+```
+
+## Error responses
+
+### 401 unauthorized
+
+```json
+{
+  "detail": "Invalid authentication credentials"
+}
+
+```
+
+**Cause:** Missing or invalid Operator Bearer Token
+
+**Solution:** Ensure you're using a valid operator token in the Authorization header
+
+### 404 not found
+
+```json
+{
+  "detail": "Workspace not found"
+}
+
+```
+
+**Cause:** The specified workspace ID does not exist
+
+**Solution:** Verify the workspace ID and ensure it belongs to your organization
+
+### 422 validation error
+
+```json
+{
+  "detail": [
+    {
+      "loc": ["body", "status"],
+      "msg": "value is not a valid enumeration member; permitted: 'active', 'inactive'",
+      "type": "type_error.enum"
+    }
+  ]
+}
+
+```
+
+**Cause:** Invalid request parameters
+
+**Solution:** Check that all parameters match the expected format and values
diff --git a/docs/vale-styles/config/vocabularies/Airbyte/accept.txt b/docs/vale-styles/config/vocabularies/Airbyte/accept.txt
index 0d5b8db9b8d2..6bd8a4436137 100644
--- a/docs/vale-styles/config/vocabularies/Airbyte/accept.txt
+++ b/docs/vale-styles/config/vocabularies/Airbyte/accept.txt
@@ -88,6 +88,40 @@ Slack
 [Ii]nitialisms
 \bCPU(?:s)?\b
 
+# API and technical terms
+
+CLI
+CLIs
+UUIDs
+JWT
+JWTs
+CORS
+SaaS
+config
+rollout
+CRM
+JSON
+jmespath
+Jmespath
+JMESPath
+Cron
+crons
+subdirectory
+subdirectories
+workspace_id
+source_id
+connection_id
+template_id
+workspaceId
+sourceId
+connectionId
+templateId
+sync_on_create
+non_breaking_changes_preference
+Onboarding
+datetime
+workspace's
+
 # Never lint Docusaurus admonitions markup
 :::
 :::note