npm - @fluentcommerce/fc-connect-sdk - Versions diffs - 0.1.53 → 0.1.55 - Mend

@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (495) hide show

package/docs/04-REFERENCE/platforms/versori/platforms-versori-webhook-api-key-security.md CHANGED Viewed

@@ -1,816 +1,816 @@
-# Securing Versori Webhooks with Connection-Based API Key Authentication (Zero Code Required)
-**Platform:** Versori
-**Level:** Beginner
-**Estimated Time:** 10 minutes
----
-## Overview
-Versori provides **built-in API key authentication** for webhooks through the connection system. When you configure a connection with API key authentication and reference it in your webhook definition, the platform automatically validates all incoming requests **before your code runs**.
-**Zero validation code required!**
-### Key Benefits
-- **Platform-managed security** - Validation happens before your code executes
-- **No code required** - Just reference the connection by name
-- **401 rejection automatic** - Invalid requests never reach your code
-- **Simple configuration** - Set up once in Versori Dashboard
-- **Easy rotation** - Update keys in UI without code changes
-- **Works for both** - Incoming webhooks AND outgoing API calls
----
-## How It Works
-### The Platform Validation Flow
-```
-┌─────────────────┐
-│  External       │
-│  System         │
-└────────┬────────┘
-         │
-         │ POST /webhook/order-create
-         │ Headers:
-         │   (as configured on the connection)
-         │ Body: { order data }
-         ▼
-   ┌─────────────────────────────────────┐
-   │  Versori Platform                   │
-   │  ┌───────────────────────────────┐  │
-   │  │ 1. Connection-based auth      │  │
-   │  │ 2. Load connection config      │  │
-   │  │ 3. Compare header to expected  │  │
-   │  │ 4. Reject if mismatch (401)    │  │
-   │  └───────────────────────────────┘  │
-   └────────────────┬────────────────────┘
-                    │
-                    │ ✅ Auth passed
-                    ▼
-          ┌──────────────────┐
-          │  Your Code       │
-          │  (executes only  │
-          │   if auth valid) │
-          └──────────────────┘
-```
-**Critical Point:** If your code runs, authentication already succeeded!
----
-## Configuration
-### Step 1: Configure Connection in Versori Dashboard
-1. **Navigate to Connections**
-   - Open Versori Dashboard
-   - Go to **Connections** tab
-   - Click **"Add Connection"**
-2. **Create API Key Connection**
-   ```
-   Connection Settings:
-   ├── Name: my-webhook-auth
-   ├── Description: API key for incoming webhooks
-   ├── Type: API Key
-   └── Configuration:
-       └── Configure authentication on the Versori connection (no inline headers)
-   ```
-3. **Save Connection**
-   - Click **"Save"**
-   - Note the connection name (`my-webhook-auth`) for use in code
-### Step 2: Generate Strong API Key
-**Use cryptographically secure generation:**
-```bash
-# Node.js - Generate 64-character key
-node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
-# Output (example):
-# 7f3e9a2b1c8d6e4f5a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f
-```
-**Key Requirements:**
-- Minimum 32 characters (64+ recommended)
-- Cryptographically random generation
-- Alphanumeric characters
-- Unique per environment/webhook
-### Step 3: Distribute API Key to Callers
-**Provide the API key to systems that will call your webhook:**
-```bash
-# Share with caller via secure channel
-# Connection-level authentication configured in Versori UI
-```
-**Never:**
-- Commit keys to version control
-- Share keys via email/chat
-- Use the same key across environments
-- Log full keys in application logs
----
-## Implementation
-### Basic Webhook with API Key Authentication
-**The simplest possible secure webhook:**
-```typescript
-import { webhook, http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-/**
- * Secure webhook with platform-managed API key authentication
- *
- * Platform validates requests via the configured connection automatically.
- * If this code runs, authentication already succeeded!
- *
- * Required connection: 'order-webhook-auth' (type: API Key)
- */
-export const secureOrderWebhook = webhook('secure-order', {
-  connection: 'order-webhook-auth', // ← Platform validates incoming requests!
-  response: { mode: 'sync' },
-}).then(
-  http('process-order', { connection: 'fluent_commerce' }, async ctx => {
-    const { log, data } = ctx;
-    // ✅ If we're here, API key validation already passed!
-    // No manual validation code needed!
-    log.info('Processing authenticated order', {
-      orderId: data?.orderId,
-    });
-    const client = await createClient(ctx);
-    // Your business logic here
-    const result = await processOrder(client, data);
-    return {
-      success: true,
-      orderId: data.orderId,
-      result,
-    };
-  })
-);
-```
-**That's it!** The platform handles everything else.
----
-## Complete Examples
-### Example 1: Simple Webhook with API Key Protection
-**Use Case:** External system sends order data, webhook validates and processes it.
-```typescript
-import { webhook, http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-/**
- * Secure order ingestion webhook
- *
- * Connection: 'order-webhook-auth'
- * - Configure authentication on the connection; do not pass headers in code examples
- */
-export const orderIngestion = webhook('order-ingestion', {
-  connection: 'order-webhook-auth', // ← Platform handles auth
-  response: { mode: 'sync' },
-}).then(
-  http('process', { connection: 'fluent_commerce' }, async ctx => {
-    const { log, data } = ctx;
-    // Authentication validated by platform before reaching here
-    log.info('Authenticated order received', { orderId: data.orderId });
-    const client = await createClient(ctx);
-    // Create Fluent order
-    const mutation = `
-      mutation CreateOrder($input: CreateOrderInput!) {
-        createOrder(input: $input) {
-          id
-          ref
-          status
-        }
-      }
-    `;
-    const result = await client.graphql({
-      query: mutation,
-      variables: {
-        input: {
-          ref: data.orderId,
-          type: data.orderType,
-          customer: data.customer,
-        },
-      },
-    });
-    log.info('Order created', {
-      fluentOrderId: result.data.createOrder.id,
-    });
-    return {
-      success: true,
-      orderId: data.orderId,
-      fluentOrderId: result.data.createOrder.id,
-    };
-  })
-);
-```
-### Example 2: Dual Connections (Incoming + Outgoing)
-**Use Case:** Receive webhook (authenticate incoming), then call external API (authenticate outgoing).
-```typescript
-import { webhook, http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-/**
- * Combined authentication pattern:
- * 1. Incoming: Platform validates webhook caller (connection: 'inventory-webhook-auth')
- * 2. Outgoing: Platform adds auth headers to external API (connection: 'external_api')
- *
- * Required connections:
- * - 'inventory-webhook-auth': API Key for incoming requests
- * - 'external_api': API Key for outgoing requests
- * - 'fluent_commerce': OAuth2 for Fluent API
- */
-export const inventoryValidation = webhook('inventory-validation', {
-  connection: 'inventory-webhook-auth', // ← Platform validates incoming request
-  response: { mode: 'sync' },
-})
-  .then(
-    http(
-      'validate-external',
-      {
-        connection: 'external_api', // ← Platform adds auth headers to outgoing requests
-      },
-      async ctx => {
-        const { log, data } = ctx;
-        // ✅ Incoming authentication already validated by platform
-        log.info('Validating inventory with external system', {
-          sku: data.sku,
-        });
-        // Call external API - auth headers automatically added by platform
-        const response = await ctx.fetch('https://api.external.com/validate', {
-          method: 'POST',
-          body: JSON.stringify({ sku: data.sku }),
-          headers: { 'Content-Type': 'application/json' },
-          // Auth headers automatically added by Versori
-        });
-        const validation = await response.json();
-        return {
-          step: 'validation',
-          sku: data.sku,
-          valid: validation.valid,
-        };
-      }
-    )
-  )
-  .then(
-    http(
-      'update-fluent',
-      {
-        connection: 'fluent_commerce',
-      },
-      async ctx => {
-        const { log, data } = ctx;
-        // Update Fluent with validation result
-        const client = await createClient(ctx);
-        const mutation = `
-      mutation UpdateInventory($input: UpdateInventoryInput!) {
-        updateInventory(input: $input) {
-          id
-          ref
-        }
-      }
-    `;
-        await client.graphql({
-          query: mutation,
-          variables: {
-            input: {
-              ref: data.sku,
-              validated: data.valid,
-            },
-          },
-        });
-        log.info('Inventory updated in Fluent', {
-          sku: data.sku,
-          valid: data.valid,
-        });
-        return {
-          success: true,
-          sku: data.sku,
-          validated: data.valid,
-        };
-      }
-    )
-  );
-```
-### Example 3: Real-World - Ad-Hoc Extraction Webhook
-**Use Case:** Trigger on-demand data extraction via authenticated webhook.
-```typescript
-import { webhook, http } from '@versori/run';
-import { createClient, ExtractionOrchestrator } from '@fluentcommerce/fc-connect-sdk';
-/**
- * Ad-hoc virtual positions extraction
- *
- * Triggered by external system with API key authentication.
- * Extracts data from Fluent and returns results.
- *
- * Connection: 'extraction-webhook-auth'
- * - Use a dedicated connection for extraction triggers with appropriate authentication
- */
-export const adhocExtraction = webhook('adhoc-extraction', {
-  connection: 'extraction-webhook-auth', // ← Platform validates before execution
-  response: { mode: 'sync' },
-}).then(
-  http('extract', { connection: 'fluent_commerce' }, async ctx => {
-    const { log, data, activation } = ctx;
-    // ✅ Authentication already validated by platform
-    // If we're here, the caller provided valid API key
-    log.info('Starting ad-hoc extraction', {
-      requestedBy: data.requestedBy,
-      filters: data.filters,
-    });
-    const client = await createClient(ctx);
-    // Build query based on request parameters
-    const query = `
-      query GetVirtualPositions(
-        $first: Int,
-        $after: String,
-        $locationRef: [String!]
-      ) {
-        virtualPositions(
-          first: $first,
-          after: $after,
-          locationRef: $locationRef
-        ) {
-          edges {
-            node {
-              id
-              ref
-              productRef
-              quantity
-            }
-          }
-          pageInfo {
-            hasNextPage
-            endCursor
-          }
-        }
-      }
-    `;
-    // Use ExtractionOrchestrator for pagination
-    const orchestrator = new ExtractionOrchestrator(client, log);
-    const results = await orchestrator.extractWithPagination({
-      query,
-      variables: {
-        locationRef: data.filters?.locations || null,
-      },
-      dataPath: 'virtualPositions',
-      pageSize: 100,
-      maxPages: 50,
-    });
-    log.info('Extraction completed', {
-      totalRecords: results.data.length,
-    });
-    return {
-      success: true,
-      recordCount: results.data.length,
-      data: results.data,
-      metadata: {
-        requestedBy: data.requestedBy,
-        timestamp: new Date().toISOString(),
-      },
-    };
-  })
-);
-```
----
-## Testing
-### Test with Valid API Key
-**Expected: 200 OK, workflow executes:**
-```bash
-curl -X POST https://yourworkspace.versori.run/webhooks/secure-order \
-  -H "X-API-Key: 7f3e9a2b1c8d6e4f5a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "orderId": "ORD-123",
-    "orderType": "STANDARD",
-    "customer": { "email": "test@example.com" }
-  }'
-# Response:
-# HTTP/1.1 200 OK
-# {
-#   "success": true,
-#   "orderId": "ORD-123",
-#   "fluentOrderId": "123456"
-# }
-```
-### Test with Missing API Key
-**Expected: 401 Unauthorized, code never runs:**
-```bash
-curl -X POST https://yourworkspace.versori.run/webhooks/secure-order \
-  -H "Content-Type: application/json" \
-  -d '{
-    "orderId": "ORD-123",
-    "orderType": "STANDARD"
-  }'
-# Response:
-# HTTP/1.1 401 Unauthorized
-# {
-#   "error": "Missing authentication",
-#   "message": "X-API-Key header required"
-# }
-```
-### Test with Invalid API Key
-**Expected: 401 Unauthorized, code never runs:**
-```bash
-curl -X POST https://yourworkspace.versori.run/webhooks/secure-order \
-  -H "X-API-Key: wrong-key-12345" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "orderId": "ORD-123",
-    "orderType": "STANDARD"
-  }'
-# Response:
-# HTTP/1.1 401 Unauthorized
-# {
-#   "error": "Invalid authentication",
-#   "message": "API key validation failed"
-# }
-```
-### Test Outgoing API Call
-**Verify platform adds auth headers automatically:**
-```typescript
-export const debugConnection = http(
-  'debug',
-  {
-    connection: 'external_api',
-  },
-  async ctx => {
-    const { log } = ctx;
-    // Log connection details (never log actual keys!)
-    const conn = ctx.activation?.connection;
-    log.info('Connection loaded', {
-      hasUrl: !!conn?.url,
-      hasHeaders: !!conn?.headers,
-      headerNames: Object.keys(conn?.headers || {}),
-    });
-    // Test API call - auth headers automatically added
-    try {
-      const response = await ctx.fetch('https://api.external.com/health');
-      log.info('Connection test succeeded', {
-        status: response.status,
-        ok: response.ok,
-      });
-      return { success: true, connected: true };
-    } catch (error) {
-      log.error('Connection test failed', { error: error.message });
-      return { success: false, error: error.message };
-    }
-  }
-);
-```
----
-## Best Practices
-### 1. Use Strong, Random Keys
-```bash
-# ✅ CORRECT - 64 characters, cryptographically random
-node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
-# Output: 7f3e9a2b1c8d6e4f5a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f
-# ❌ WRONG - Short, predictable
-X-API-Key: secret123
-```
-### 2. One Connection Per Webhook/Purpose
-```typescript
-// ✅ CORRECT - Separate connections for different purposes
-export const orderWebhook = webhook('orders', {
-  connection: 'order-webhook-auth', // Orders connection
-});
-export const inventoryWebhook = webhook('inventory', {
-  connection: 'inventory-webhook-auth', // Inventory connection
-});
-// ❌ WRONG - Shared key across different systems
-export const orderWebhook = webhook('orders', {
-  connection: 'shared-webhook-auth', // Don't reuse!
-});
-```
-### 3. Rotate Keys Regularly
-**Update in Versori Dashboard (no code changes needed):**
-1. Generate new key: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`
-2. Update connection in Versori Dashboard
-3. Distribute new key to callers
-4. No code deployment required!
-**Rotation Schedule:**
-- Development: Every 90 days
-- Staging: Every 60 days
-- Production: Every 30 days
-### 4. Document Connection Requirements
-```typescript
-/**
- * Secure Order Processing Webhook
- *
- * Required Connections:
- * 1. 'order-webhook-auth' (API Key - Incoming)
- *    - Authentication is enforced by the Versori connection prior to code execution
- *
- * 2. 'fluent_commerce' (OAuth2 - Outgoing)
- *    - Type: OAuth2
- *    - Purpose: Authenticate requests to Fluent API
- *
- * Setup:
- * 1. Create both connections in Versori Dashboard
- * 2. Provide X-API-Key to webhook callers
- * 3. Deploy webhook
- */
-export const secureOrderWebhook = webhook('secure-order', {
-  connection: 'order-webhook-auth',
-  // ... rest of webhook
-});
-```
-### 5. Log Security Events (Safely)
-```typescript
-export const secureWebhook = webhook('secure', {
-  connection: 'webhook-auth',
-  response: { mode: 'sync' },
-}).then(
-  http('process', { connection: 'fluent' }, async ctx => {
-    const { log, data, request } = ctx;
-    // ✅ CORRECT - Log without exposing keys
-    const req = request();
-    log.info('Authenticated request received', {
-      endpoint: req.url,
-      method: req.method,
-      hasApiKey: !!req.headers.get('x-api-key'),
-      keyPrefix: req.headers.get('x-api-key')?.substring(0, 8) + '...',
-      ipAddress: req.headers.get('x-forwarded-for'),
-      timestamp: new Date().toISOString(),
-    });
-    // ❌ WRONG - Exposes full API key
-    log.info('Request', {
-      apiKey: req.headers.get('x-api-key'), // NEVER log full keys!
-    });
-    // Process request...
-  })
-);
-```
-### 6. Use Descriptive Connection Names
-```typescript
-// ✅ CORRECT - Clear purpose
-connection: 'order-webhook-auth';
-connection: 'inventory-extraction-trigger';
-connection: 'shopify-order-sync-webhook';
-// ❌ WRONG - Vague names
-connection: 'webhook1';
-connection: 'api-key';
-connection: 'auth';
-```
----
-## Troubleshooting
-### Issue: 401 Unauthorized (Valid Key)
-**Symptoms:**
-- You're providing the correct API key
-- Still getting 401 Unauthorized
-- Code never executes
-**Possible Causes:**
-1. **Header name mismatch:**
-   ```bash
-   # Check connection config - must match exactly
-   Connection: X-API-Key (configured)
-   Request: x-api-key (sent)  # ❌ Case-sensitive!
-   ```
-2. **Whitespace in key:**
-   ```bash
-   # ❌ WRONG - Extra space
-   curl -H "X-API-Key: abc123 "
-   # ✅ CORRECT - No whitespace
-   curl -H "X-API-Key: abc123"
-   ```
-3. **Wrong connection name:**
-   ```typescript
-   // Webhook references: 'order-webhook-auth'
-   webhook('orders', { connection: 'order-webhook-auth' });
-   // But connection in UI is named: 'order-webhook'  ❌
-   // Fix: Match names exactly!
-   ```
-### Issue: Connection Not Found
-**Symptoms:**
-- Error: "Connection not found"
-- Webhook fails to start
-**Solution:**
-1. Verify connection exists in Versori Dashboard
-2. Check connection name matches exactly (case-sensitive)
-3. Ensure connection is saved and active
-### Issue: Auth Headers Not Added (Outgoing)
-**Symptoms:**
-- External API returns 401
-- Auth headers missing from request
-- Outgoing API call fails
-**Solution:**
-1. Verify `connection` parameter specified in `http()` options:
-   ```typescript
-   // ✅ CORRECT
-   .then(http('call-api', { connection: 'external_api' }, async (ctx) => {
-     await ctx.fetch('https://api.external.com/data');
-   }))
-   // ❌ WRONG - Missing connection
-   .then(http('call-api', async (ctx) => {
-     await ctx.fetch('https://api.external.com/data');
-   }))
-   ```
-2. Check connection configuration in Versori Dashboard
-3. Verify connection type matches API requirements
-### Issue: Need Different Keys Per Environment
-**Solution:** Use environment-specific connections:
-```typescript
-// Development environment
-webhook('orders-dev', { connection: 'order-webhook-auth-dev' });
-// Production environment
-webhook('orders-prod', { connection: 'order-webhook-auth-prod' });
-```
-Configure different keys in Versori Dashboard for each environment.
----
-## Summary
-### Key Takeaways
-**Connection-Based Authentication (Recommended):**
-- ✅ Zero validation code required
-- ✅ Platform validates before code runs
-- ✅ Configure once in Versori Dashboard
-- ✅ Reference by name: `{ connection: 'webhook-auth' }`
-- ✅ Works for incoming AND outgoing requests
-- ✅ Rotate keys in UI without code changes
-- ✅ Automatic 401 rejection for invalid requests
-**The Magic Line:**
-```typescript
-webhook('my-webhook', {
-  connection: 'webhook-auth', // ← This ONE line enables platform validation
-});
-```
-### Quick Decision Guide
-| Scenario                        | Pattern                 | Code Required |
-| ------------------------------- | ----------------------- | ------------- |
-| **Incoming webhook needs auth** | Connection-based        | Zero          |
-| **Webhook calls external API**  | Connection-based        | Zero          |
-| **Both incoming + outgoing**    | Connection-based (both) | Zero          |
-| **Custom auth algorithm**       | Manual validation       | Moderate      |
-### Setup Checklist
-- [ ] Generate strong API key (64+ characters)
-- [ ] Create connection in Versori Dashboard
-- [ ] Configure API Key type and header name
-- [ ] Add connection to webhook definition
-- [ ] Distribute key to webhook callers
-- [ ] Test with valid/invalid keys
-- [ ] Document connection requirements
-- [ ] Set up key rotation schedule
----
-## Related Documentation
-- [Module 5: Connection Management](./modules/platforms-versori-05-connections.md) - Detailed connection configuration
-- [Webhook Validation Guide](../../../02-CORE-GUIDES/webhook-validation/webhook-validation-readme.md) - Cryptographic signature validation (Fluent webhooks)
-- [Module 3: Versori Integration](../../../02-CORE-GUIDES/webhook-validation/modules/webhook-validation-03-versori-integration.md) - Combining API keys with signatures
-- [KV State Management Pattern](../../../01-TEMPLATES/versori/patterns/kv-state-management.md) - Request deduplication
-- [XML Response Patterns](../../../01-TEMPLATES/versori/patterns/xml-response-patterns.md) - Custom response formats
----
-**Document Version:** 4.0 (Final - Connection-Based Only)
-**Maintained By:** FC Connect SDK Team
-**Changelog:**
-- v4.0: **Cleanup** - Focused on connection-based patterns
-- v3.0: Major rewrite - Documented connection-based pattern
-- v2.0: Clarified use cases
-- v1.0: Initial version
+# Securing Versori Webhooks with Connection-Based API Key Authentication (Zero Code Required)
+**Platform:** Versori
+**Level:** Beginner
+**Estimated Time:** 10 minutes
+---
+## Overview
+Versori provides **built-in API key authentication** for webhooks through the connection system. When you configure a connection with API key authentication and reference it in your webhook definition, the platform automatically validates all incoming requests **before your code runs**.
+**Zero validation code required!**
+### Key Benefits
+- **Platform-managed security** - Validation happens before your code executes
+- **No code required** - Just reference the connection by name
+- **401 rejection automatic** - Invalid requests never reach your code
+- **Simple configuration** - Set up once in Versori Dashboard
+- **Easy rotation** - Update keys in UI without code changes
+- **Works for both** - Incoming webhooks AND outgoing API calls
+---
+## How It Works
+### The Platform Validation Flow
+```
+┌─────────────────┐
+│  External       │
+│  System         │
+└────────┬────────┘
+         │
+         │ POST /webhook/order-create
+         │ Headers:
+         │   (as configured on the connection)
+         │ Body: { order data }
+         ▼
+   ┌─────────────────────────────────────┐
+   │  Versori Platform                   │
+   │  ┌───────────────────────────────┐  │
+   │  │ 1. Connection-based auth      │  │
+   │  │ 2. Load connection config      │  │
+   │  │ 3. Compare header to expected  │  │
+   │  │ 4. Reject if mismatch (401)    │  │
+   │  └───────────────────────────────┘  │
+   └────────────────┬────────────────────┘
+                    │
+                    │ ✅ Auth passed
+                    ▼
+          ┌──────────────────┐
+          │  Your Code       │
+          │  (executes only  │
+          │   if auth valid) │
+          └──────────────────┘
+```
+**Critical Point:** If your code runs, authentication already succeeded!
+---
+## Configuration
+### Step 1: Configure Connection in Versori Dashboard
+1. **Navigate to Connections**
+   - Open Versori Dashboard
+   - Go to **Connections** tab
+   - Click **"Add Connection"**
+2. **Create API Key Connection**
+   ```
+   Connection Settings:
+   ├── Name: my-webhook-auth
+   ├── Description: API key for incoming webhooks
+   ├── Type: API Key
+   └── Configuration:
+       └── Configure authentication on the Versori connection (no inline headers)
+   ```
+3. **Save Connection**
+   - Click **"Save"**
+   - Note the connection name (`my-webhook-auth`) for use in code
+### Step 2: Generate Strong API Key
+**Use cryptographically secure generation:**
+```bash
+# Node.js - Generate 64-character key
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+# Output (example):
+# 7f3e9a2b1c8d6e4f5a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f
+```
+**Key Requirements:**
+- Minimum 32 characters (64+ recommended)
+- Cryptographically random generation
+- Alphanumeric characters
+- Unique per environment/webhook
+### Step 3: Distribute API Key to Callers
+**Provide the API key to systems that will call your webhook:**
+```bash
+# Share with caller via secure channel
+# Connection-level authentication configured in Versori UI
+```
+**Never:**
+- Commit keys to version control
+- Share keys via email/chat
+- Use the same key across environments
+- Log full keys in application logs
+---
+## Implementation
+### Basic Webhook with API Key Authentication
+**The simplest possible secure webhook:**
+```typescript
+import { webhook, http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+/**
+ * Secure webhook with platform-managed API key authentication
+ *
+ * Platform validates requests via the configured connection automatically.
+ * If this code runs, authentication already succeeded!
+ *
+ * Required connection: 'order-webhook-auth' (type: API Key)
+ */
+export const secureOrderWebhook = webhook('secure-order', {
+  connection: 'order-webhook-auth', // ← Platform validates incoming requests!
+  response: { mode: 'sync' },
+}).then(
+  http('process-order', { connection: 'fluent_commerce' }, async ctx => {
+    const { log, data } = ctx;
+    // ✅ If we're here, API key validation already passed!
+    // No manual validation code needed!
+    log.info('Processing authenticated order', {
+      orderId: data?.orderId,
+    });
+    const client = await createClient(ctx);
+    // Your business logic here
+    const result = await processOrder(client, data);
+    return {
+      success: true,
+      orderId: data.orderId,
+      result,
+    };
+  })
+);
+```
+**That's it!** The platform handles everything else.
+---
+## Complete Examples
+### Example 1: Simple Webhook with API Key Protection
+**Use Case:** External system sends order data, webhook validates and processes it.
+```typescript
+import { webhook, http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+/**
+ * Secure order ingestion webhook
+ *
+ * Connection: 'order-webhook-auth'
+ * - Configure authentication on the connection; do not pass headers in code examples
+ */
+export const orderIngestion = webhook('order-ingestion', {
+  connection: 'order-webhook-auth', // ← Platform handles auth
+  response: { mode: 'sync' },
+}).then(
+  http('process', { connection: 'fluent_commerce' }, async ctx => {
+    const { log, data } = ctx;
+    // Authentication validated by platform before reaching here
+    log.info('Authenticated order received', { orderId: data.orderId });
+    const client = await createClient(ctx);
+    // Create Fluent order
+    const mutation = `
+      mutation CreateOrder($input: CreateOrderInput!) {
+        createOrder(input: $input) {
+          id
+          ref
+          status
+        }
+      }
+    `;
+    const result = await client.graphql({
+      query: mutation,
+      variables: {
+        input: {
+          ref: data.orderId,
+          type: data.orderType,
+          customer: data.customer,
+        },
+      },
+    });
+    log.info('Order created', {
+      fluentOrderId: result.data.createOrder.id,
+    });
+    return {
+      success: true,
+      orderId: data.orderId,
+      fluentOrderId: result.data.createOrder.id,
+    };
+  })
+);
+```
+### Example 2: Dual Connections (Incoming + Outgoing)
+**Use Case:** Receive webhook (authenticate incoming), then call external API (authenticate outgoing).
+```typescript
+import { webhook, http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+/**
+ * Combined authentication pattern:
+ * 1. Incoming: Platform validates webhook caller (connection: 'inventory-webhook-auth')
+ * 2. Outgoing: Platform adds auth headers to external API (connection: 'external_api')
+ *
+ * Required connections:
+ * - 'inventory-webhook-auth': API Key for incoming requests
+ * - 'external_api': API Key for outgoing requests
+ * - 'fluent_commerce': OAuth2 for Fluent API
+ */
+export const inventoryValidation = webhook('inventory-validation', {
+  connection: 'inventory-webhook-auth', // ← Platform validates incoming request
+  response: { mode: 'sync' },
+})
+  .then(
+    http(
+      'validate-external',
+      {
+        connection: 'external_api', // ← Platform adds auth headers to outgoing requests
+      },
+      async ctx => {
+        const { log, data } = ctx;
+        // ✅ Incoming authentication already validated by platform
+        log.info('Validating inventory with external system', {
+          sku: data.sku,
+        });
+        // Call external API - auth headers automatically added by platform
+        const response = await ctx.fetch('https://api.external.com/validate', {
+          method: 'POST',
+          body: JSON.stringify({ sku: data.sku }),
+          headers: { 'Content-Type': 'application/json' },
+          // Auth headers automatically added by Versori
+        });
+        const validation = await response.json();
+        return {
+          step: 'validation',
+          sku: data.sku,
+          valid: validation.valid,
+        };
+      }
+    )
+  )
+  .then(
+    http(
+      'update-fluent',
+      {
+        connection: 'fluent_commerce',
+      },
+      async ctx => {
+        const { log, data } = ctx;
+        // Update Fluent with validation result
+        const client = await createClient(ctx);
+        const mutation = `
+      mutation UpdateInventory($input: UpdateInventoryInput!) {
+        updateInventory(input: $input) {
+          id
+          ref
+        }
+      }
+    `;
+        await client.graphql({
+          query: mutation,
+          variables: {
+            input: {
+              ref: data.sku,
+              validated: data.valid,
+            },
+          },
+        });
+        log.info('Inventory updated in Fluent', {
+          sku: data.sku,
+          valid: data.valid,
+        });
+        return {
+          success: true,
+          sku: data.sku,
+          validated: data.valid,
+        };
+      }
+    )
+  );
+```
+### Example 3: Real-World - Ad-Hoc Extraction Webhook
+**Use Case:** Trigger on-demand data extraction via authenticated webhook.
+```typescript
+import { webhook, http } from '@versori/run';
+import { createClient, ExtractionOrchestrator } from '@fluentcommerce/fc-connect-sdk';
+/**
+ * Ad-hoc virtual positions extraction
+ *
+ * Triggered by external system with API key authentication.
+ * Extracts data from Fluent and returns results.
+ *
+ * Connection: 'extraction-webhook-auth'
+ * - Use a dedicated connection for extraction triggers with appropriate authentication
+ */
+export const adhocExtraction = webhook('adhoc-extraction', {
+  connection: 'extraction-webhook-auth', // ← Platform validates before execution
+  response: { mode: 'sync' },
+}).then(
+  http('extract', { connection: 'fluent_commerce' }, async ctx => {
+    const { log, data, activation } = ctx;
+    // ✅ Authentication already validated by platform
+    // If we're here, the caller provided valid API key
+    log.info('Starting ad-hoc extraction', {
+      requestedBy: data.requestedBy,
+      filters: data.filters,
+    });
+    const client = await createClient(ctx);
+    // Build query based on request parameters
+    const query = `
+      query GetVirtualPositions(
+        $first: Int,
+        $after: String,
+        $locationRef: [String!]
+      ) {
+        virtualPositions(
+          first: $first,
+          after: $after,
+          locationRef: $locationRef
+        ) {
+          edges {
+            node {
+              id
+              ref
+              productRef
+              quantity
+            }
+          }
+          pageInfo {
+            hasNextPage
+            endCursor
+          }
+        }
+      }
+    `;
+    // Use ExtractionOrchestrator for pagination
+    const orchestrator = new ExtractionOrchestrator(client, log);
+    const results = await orchestrator.extractWithPagination({
+      query,
+      variables: {
+        locationRef: data.filters?.locations || null,
+      },
+      dataPath: 'virtualPositions',
+      pageSize: 100,
+      maxPages: 50,
+    });
+    log.info('Extraction completed', {
+      totalRecords: results.data.length,
+    });
+    return {
+      success: true,
+      recordCount: results.data.length,
+      data: results.data,
+      metadata: {
+        requestedBy: data.requestedBy,
+        timestamp: new Date().toISOString(),
+      },
+    };
+  })
+);
+```
+---
+## Testing
+### Test with Valid API Key
+**Expected: 200 OK, workflow executes:**
+```bash
+curl -X POST https://yourworkspace.versori.run/webhooks/secure-order \
+  -H "X-API-Key: 7f3e9a2b1c8d6e4f5a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "orderId": "ORD-123",
+    "orderType": "STANDARD",
+    "customer": { "email": "test@example.com" }
+  }'
+# Response:
+# HTTP/1.1 200 OK
+# {
+#   "success": true,
+#   "orderId": "ORD-123",
+#   "fluentOrderId": "123456"
+# }
+```
+### Test with Missing API Key
+**Expected: 401 Unauthorized, code never runs:**
+```bash
+curl -X POST https://yourworkspace.versori.run/webhooks/secure-order \
+  -H "Content-Type: application/json" \
+  -d '{
+    "orderId": "ORD-123",
+    "orderType": "STANDARD"
+  }'
+# Response:
+# HTTP/1.1 401 Unauthorized
+# {
+#   "error": "Missing authentication",
+#   "message": "X-API-Key header required"
+# }
+```
+### Test with Invalid API Key
+**Expected: 401 Unauthorized, code never runs:**
+```bash
+curl -X POST https://yourworkspace.versori.run/webhooks/secure-order \
+  -H "X-API-Key: wrong-key-12345" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "orderId": "ORD-123",
+    "orderType": "STANDARD"
+  }'
+# Response:
+# HTTP/1.1 401 Unauthorized
+# {
+#   "error": "Invalid authentication",
+#   "message": "API key validation failed"
+# }
+```
+### Test Outgoing API Call
+**Verify platform adds auth headers automatically:**
+```typescript
+export const debugConnection = http(
+  'debug',
+  {
+    connection: 'external_api',
+  },
+  async ctx => {
+    const { log } = ctx;
+    // Log connection details (never log actual keys!)
+    const conn = ctx.activation?.connection;
+    log.info('Connection loaded', {
+      hasUrl: !!conn?.url,
+      hasHeaders: !!conn?.headers,
+      headerNames: Object.keys(conn?.headers || {}),
+    });
+    // Test API call - auth headers automatically added
+    try {
+      const response = await ctx.fetch('https://api.external.com/health');
+      log.info('Connection test succeeded', {
+        status: response.status,
+        ok: response.ok,
+      });
+      return { success: true, connected: true };
+    } catch (error) {
+      log.error('Connection test failed', { error: error.message });
+      return { success: false, error: error.message };
+    }
+  }
+);
+```
+---
+## Best Practices
+### 1. Use Strong, Random Keys
+```bash
+# ✅ CORRECT - 64 characters, cryptographically random
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+# Output: 7f3e9a2b1c8d6e4f5a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f
+# ❌ WRONG - Short, predictable
+X-API-Key: secret123
+```
+### 2. One Connection Per Webhook/Purpose
+```typescript
+// ✅ CORRECT - Separate connections for different purposes
+export const orderWebhook = webhook('orders', {
+  connection: 'order-webhook-auth', // Orders connection
+});
+export const inventoryWebhook = webhook('inventory', {
+  connection: 'inventory-webhook-auth', // Inventory connection
+});
+// ❌ WRONG - Shared key across different systems
+export const orderWebhook = webhook('orders', {
+  connection: 'shared-webhook-auth', // Don't reuse!
+});
+```
+### 3. Rotate Keys Regularly
+**Update in Versori Dashboard (no code changes needed):**
+1. Generate new key: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`
+2. Update connection in Versori Dashboard
+3. Distribute new key to callers
+4. No code deployment required!
+**Rotation Schedule:**
+- Development: Every 90 days
+- Staging: Every 60 days
+- Production: Every 30 days
+### 4. Document Connection Requirements
+```typescript
+/**
+ * Secure Order Processing Webhook
+ *
+ * Required Connections:
+ * 1. 'order-webhook-auth' (API Key - Incoming)
+ *    - Authentication is enforced by the Versori connection prior to code execution
+ *
+ * 2. 'fluent_commerce' (OAuth2 - Outgoing)
+ *    - Type: OAuth2
+ *    - Purpose: Authenticate requests to Fluent API
+ *
+ * Setup:
+ * 1. Create both connections in Versori Dashboard
+ * 2. Provide X-API-Key to webhook callers
+ * 3. Deploy webhook
+ */
+export const secureOrderWebhook = webhook('secure-order', {
+  connection: 'order-webhook-auth',
+  // ... rest of webhook
+});
+```
+### 5. Log Security Events (Safely)
+```typescript
+export const secureWebhook = webhook('secure', {
+  connection: 'webhook-auth',
+  response: { mode: 'sync' },
+}).then(
+  http('process', { connection: 'fluent' }, async ctx => {
+    const { log, data, request } = ctx;
+    // ✅ CORRECT - Log without exposing keys
+    const req = request();
+    log.info('Authenticated request received', {
+      endpoint: req.url,
+      method: req.method,
+      hasApiKey: !!req.headers.get('x-api-key'),
+      keyPrefix: req.headers.get('x-api-key')?.substring(0, 8) + '...',
+      ipAddress: req.headers.get('x-forwarded-for'),
+      timestamp: new Date().toISOString(),
+    });
+    // ❌ WRONG - Exposes full API key
+    log.info('Request', {
+      apiKey: req.headers.get('x-api-key'), // NEVER log full keys!
+    });
+    // Process request...
+  })
+);
+```
+### 6. Use Descriptive Connection Names
+```typescript
+// ✅ CORRECT - Clear purpose
+connection: 'order-webhook-auth';
+connection: 'inventory-extraction-trigger';
+connection: 'shopify-order-sync-webhook';
+// ❌ WRONG - Vague names
+connection: 'webhook1';
+connection: 'api-key';
+connection: 'auth';
+```
+---
+## Troubleshooting
+### Issue: 401 Unauthorized (Valid Key)
+**Symptoms:**
+- You're providing the correct API key
+- Still getting 401 Unauthorized
+- Code never executes
+**Possible Causes:**
+1. **Header name mismatch:**
+   ```bash
+   # Check connection config - must match exactly
+   Connection: X-API-Key (configured)
+   Request: x-api-key (sent)  # ❌ Case-sensitive!
+   ```
+2. **Whitespace in key:**
+   ```bash
+   # ❌ WRONG - Extra space
+   curl -H "X-API-Key: abc123 "
+   # ✅ CORRECT - No whitespace
+   curl -H "X-API-Key: abc123"
+   ```
+3. **Wrong connection name:**
+   ```typescript
+   // Webhook references: 'order-webhook-auth'
+   webhook('orders', { connection: 'order-webhook-auth' });
+   // But connection in UI is named: 'order-webhook'  ❌
+   // Fix: Match names exactly!
+   ```
+### Issue: Connection Not Found
+**Symptoms:**
+- Error: "Connection not found"
+- Webhook fails to start
+**Solution:**
+1. Verify connection exists in Versori Dashboard
+2. Check connection name matches exactly (case-sensitive)
+3. Ensure connection is saved and active
+### Issue: Auth Headers Not Added (Outgoing)
+**Symptoms:**
+- External API returns 401
+- Auth headers missing from request
+- Outgoing API call fails
+**Solution:**
+1. Verify `connection` parameter specified in `http()` options:
+   ```typescript
+   // ✅ CORRECT
+   .then(http('call-api', { connection: 'external_api' }, async (ctx) => {
+     await ctx.fetch('https://api.external.com/data');
+   }))
+   // ❌ WRONG - Missing connection
+   .then(http('call-api', async (ctx) => {
+     await ctx.fetch('https://api.external.com/data');
+   }))
+   ```
+2. Check connection configuration in Versori Dashboard
+3. Verify connection type matches API requirements
+### Issue: Need Different Keys Per Environment
+**Solution:** Use environment-specific connections:
+```typescript
+// Development environment
+webhook('orders-dev', { connection: 'order-webhook-auth-dev' });
+// Production environment
+webhook('orders-prod', { connection: 'order-webhook-auth-prod' });
+```
+Configure different keys in Versori Dashboard for each environment.
+---
+## Summary
+### Key Takeaways
+**Connection-Based Authentication (Recommended):**
+- ✅ Zero validation code required
+- ✅ Platform validates before code runs
+- ✅ Configure once in Versori Dashboard
+- ✅ Reference by name: `{ connection: 'webhook-auth' }`
+- ✅ Works for incoming AND outgoing requests
+- ✅ Rotate keys in UI without code changes
+- ✅ Automatic 401 rejection for invalid requests
+**The Magic Line:**
+```typescript
+webhook('my-webhook', {
+  connection: 'webhook-auth', // ← This ONE line enables platform validation
+});
+```
+### Quick Decision Guide
+| Scenario                        | Pattern                 | Code Required |
+| ------------------------------- | ----------------------- | ------------- |
+| **Incoming webhook needs auth** | Connection-based        | Zero          |
+| **Webhook calls external API**  | Connection-based        | Zero          |
+| **Both incoming + outgoing**    | Connection-based (both) | Zero          |
+| **Custom auth algorithm**       | Manual validation       | Moderate      |
+### Setup Checklist
+- [ ] Generate strong API key (64+ characters)
+- [ ] Create connection in Versori Dashboard
+- [ ] Configure API Key type and header name
+- [ ] Add connection to webhook definition
+- [ ] Distribute key to webhook callers
+- [ ] Test with valid/invalid keys
+- [ ] Document connection requirements
+- [ ] Set up key rotation schedule
+---
+## Related Documentation
+- [Module 5: Connection Management](./modules/platforms-versori-05-connections.md) - Detailed connection configuration
+- [Webhook Validation Guide](../../../02-CORE-GUIDES/webhook-validation/webhook-validation-readme.md) - Cryptographic signature validation (Fluent webhooks)
+- [Module 3: Versori Integration](../../../02-CORE-GUIDES/webhook-validation/modules/webhook-validation-03-versori-integration.md) - Combining API keys with signatures
+- [KV State Management Pattern](../../../01-TEMPLATES/versori/patterns/kv-state-management.md) - Request deduplication
+- [XML Response Patterns](../../../01-TEMPLATES/versori/patterns/xml-response-patterns.md) - Custom response formats
+---
+**Document Version:** 4.0 (Final - Connection-Based Only)
+**Maintained By:** FC Connect SDK Team
+**Changelog:**
+- v4.0: **Cleanup** - Focused on connection-based patterns
+- v3.0: Major rewrite - Documented connection-based pattern
+- v2.0: Clarified use cases
+- v1.0: Initial version