> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zappway.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Iframe Integration

> How ZappFlux is loaded within ZappWay and how authentication is managed automatically.

# Iframe Integration

## How the Integration Works

ZappFlux is embedded into the ZappWay dashboard as an integrated application via `<iframe>`. You access the complete flow editor, settings, and reports **without leaving ZappWay** and without needing to log into a separate account.

**Architecture:**

```
ZappWay Dashboard
└── Sidebar Menu → Tools → ZappFlux
    └── <iframe> → ZappFlux (flows, editor, settings)
        └── Automatic authentication via Bridge Session
```

**Benefits:**

* ✓ No account switching required
* ✓ Automatic authentication
* ✓ Seamless user experience
* ✓ Unified organization context
* ✓ Real-time synchronization

***

## Automatic Authentication (Bridge Session)

When you access ZappFlux through the dashboard, authentication happens automatically:

### How It Works:

**1. Session Transfer**

* ZappWay passes your active session to ZappFlux via **Bridge Session**
* No credentials or API keys needed from you

**2. Iframe Detection**

* ZappFlux detects it's running inside a ZappWay iframe
* Enables special iframe-mode features and synchronization

**3. Account Precedence**

* Your ZappWay account has **priority**
* Even if a separate ZappFlux account exists, ZappWay takes control
* Organization context is inherited from ZappWay

**4. Automatic Sync**

* Changes made in ZappFlux sync to your ZappWay organization
* Flows, settings, and data remain consistent
* No manual synchronization required

<Info>
  **You never need to log in separately to ZappFlux** when accessing it through ZappWay. The session is automatically synchronized with your active organization.
</Info>

### Security Considerations:

**Session Management:**

* Bridge Session uses secure token exchange
* Sessions expire with your ZappWay session
* No persistent credentials stored in iframe
* Automatic logout when you log out of ZappWay

**Data Isolation:**

* Organization data is properly scoped
* No cross-organization data leakage
* Secure communication between ZappWay and ZappFlux
* Industry-standard security protocols

***

## Available Routes in Dashboard

When accessing ZappFlux through ZappWay, these routes are available:

| ZappWay Route               | What Loads    | Description                                  |
| --------------------------- | ------------- | -------------------------------------------- |
| `/zappflux`                 | Auto-redirect | Automatically redirects to `/zappflux/flows` |
| `/zappflux/flows`           | Flow list     | List of all flows and automation editor      |
| `/zappflux/flows/[id]`      | Flow detail   | View specific flow details                   |
| `/zappflux/flows/[id]/edit` | Flow editor   | Edit a specific flow in visual editor        |
| `/zappflux/settings`        | Settings      | Configurations, integrations, and channels   |
| `/zappflux/analytics`       | Analytics     | Flow performance and usage statistics        |

**Navigation Examples:**

```
Dashboard → Tools → ZappFlux
→ Loads: /zappflux/flows (flow list)

Click "Edit" on a flow
→ Loads: /zappflux/flows/abc123/edit (flow editor)

Click "Settings" in ZappFlux
→ Loads: /zappflux/settings (configuration)
```

***

## Opening in New Tab

At any ZappFlux screen within the dashboard, you'll find an **"Open in New Tab"** button that allows you to access ZappFlux independently.

### Important Considerations:

<Warning>
  **When opening in a new tab, the Bridge Session is not active.** You must be logged into a separate ZappFlux account. Changes made outside the iframe may not automatically reflect in your ZappWay organization.

  **Always prefer using ZappFlux through the dashboard to ensure proper synchronization.**
</Warning>

**When to Use New Tab:**

* Need multiple ZappFlux windows open simultaneously
* Troubleshooting or comparing configurations
* Working with ZappFlux-specific features not yet in iframe
* Development or testing purposes

**When Opening in New Tab:**

1. Click **"Open in New Tab"** button in ZappFlux interface
2. New browser tab opens with ZappFlux URL
3. If not logged into ZappFlux separately, you'll see login screen
4. Log in with ZappFlux credentials (separate from ZappWay)
5. Manual synchronization may be required

**Synchronization Limitations:**

* Changes in new tab may not sync automatically
* Organization context might differ
* Requires manual refresh to see updates
* Bridge Session features unavailable

**Best Practice:**

```
✓ Use ZappFlux through ZappWay dashboard (recommended)
  → Automatic sync, seamless experience

✗ Avoid opening in new tab unless necessary
  → Manual sync, potential conflicts
```

***

## Iframe Communication

### How Data Flows:

**Dashboard to ZappFlux:**

* Organization context
* User authentication token
* Active workspace information
* Theme and UI preferences

**ZappFlux to Dashboard:**

* Flow creation/update events
* Status changes
* Error notifications
* Analytics data

**Real-time Updates:**

* Changes in ZappFlux reflect immediately in dashboard
* Dashboard changes propagate to ZappFlux iframe
* Bidirectional communication maintained

***

## Troubleshooting Iframe Integration

### Issue: ZappFlux Not Loading

**Symptoms:**

* Blank iframe
* Infinite loading spinner
* Error message in iframe

**Solutions:**

1. Refresh the page (F5 or Ctrl+R / Cmd+R)
2. Clear browser cache and cookies
3. Check browser console for errors
4. Disable browser extensions (especially ad blockers)
5. Try different browser
6. Check internet connection

### Issue: Authentication Failed

**Symptoms:**

* Login prompt appears in ZappFlux
* "Session expired" error
* Redirect to login page

**Solutions:**

1. Log out and log back into ZappWay
2. Clear cookies for zappway.ai and zappflux.zappway.ai
3. Check that cookies are enabled in browser
4. Verify you have active ZappWay session
5. Try incognito/private browsing mode

### Issue: Changes Not Saving

**Symptoms:**

* Edits don't persist
* Changes revert after refresh
* "Save failed" error

**Solutions:**

1. Check internet connection
2. Verify you have edit permissions
3. Try saving again
4. Refresh page and retry
5. Check browser console for errors
6. Contact support if persists

### Issue: Slow Performance

**Symptoms:**

* Iframe loads slowly
* Laggy editor interactions
* Delayed responses

**Solutions:**

1. Close other browser tabs
2. Clear browser cache
3. Check internet speed
4. Disable unnecessary browser extensions
5. Try different browser
6. Check system resources (RAM, CPU)

***

## Best Practices

### For Optimal Experience:

**1. Always Use Dashboard Access**

* Prefer `/zappflux` routes within ZappWay
* Ensures proper authentication and sync
* Better user experience
* Automatic organization context

**2. Avoid New Tab When Possible**

* Only open in new tab if necessary
* Remember: separate session, manual sync required
* Return to dashboard for main work

**3. Keep Browser Updated**

* Use latest browser version
* Update regularly for security and features
* Supported browsers: Chrome, Firefox, Safari, Edge

**4. Enable Cookies**

* Required for Bridge Session
* Allow cookies for zappway.ai and zappflux.zappway.ai
* Check privacy settings

**5. Monitor Console**

* Open developer console if issues occur
* Look for error messages
* Include errors when contacting support

***

## Technical Documentation

For API reference, webhook integration, and advanced technical details:

<Card title="ZappFlux Official Documentation" icon="arrow-up-right-from-square" href="https://docs.zappflux.zappway.ai">
  docs.zappflux.zappway.ai
</Card>

**Technical Resources:**

* API Reference
* Webhook Configuration
* Custom Integration Guide
* Flow Builder API
* Advanced Features

***

## Support

Need help with iframe integration?

**Contact ZappWay Support:**

* Email: [support@zappway.ai](mailto:support@zappway.ai)
* Include: Browser type/version, error messages, screenshots

**Provide These Details:**

* Which route you're accessing
* Error messages (from console if available)
* Browser and operating system
* Steps to reproduce issue
* Whether issue occurs in new tab vs iframe

***

**Last Updated:** March 2026\
**Platform:** ZappFlux Iframe Integration | ZappWay Dashboard