Flow Configuration

The Connect UI iframe supports a flowConfig option that gives you control over the pre-authorization steps shown during the connection flow. You can skip steps entirely, override their text, customize button labels, or hide buttons — all configured from your parent page through the iframe URL, with no backend changes required.

This is especially useful when embedding Unizo's unified API integrations into your product and you want the authorization experience to match your application's language, tone, and workflow.

What You Can Configure

Capability	Description
Skip steps	Auto-advance past pre-authorization steps. Skip all steps globally or target specific steps by index.
Override text	Replace the title, subtitle, or description of any step with your own copy. Fields you omit keep their original values.
Customize buttons	Rename button labels to match your product language.
Hide buttons	Remove individual option buttons from a step entirely.

How It Works

Flow configuration is passed to the Connect UI iframe through the theme URL query parameter as a JSON-encoded value. The iframe reads the flowConfig object and applies it to the connection flow.

1. Build the configuration — define your flowConfig object in JavaScript
2. Encode it into the URL — JSON-stringify the config, URL-encode it, and append it as the theme query parameter
3. Set the iframe src — the Connect UI reads the config on load and applies it to all connection flows
4. Listen for events — use postMessage to handle integration.created and connect.close events

Configuration Reference

{
  "flowConfig": {
    "attentionInfo": {
      "skip": true | false,           // Skip ALL pre-auth steps
      "steps": {
        "0": {                         // Target step by index (0-based)
          "skip": true | false,        // Skip this step
          "title": "...",              // Override step title
          "subTitle": "...",           // Override step subtitle
          "description": "...",        // Override step description
          "options": {
            "0": {
              "label": "...",          // Override button label
              "hide": true | false     // Hide this button
            }
          }
        }
      }
    },
    "scopesStep": {
      "skip": true | false             // Skip OAuth scopes consent step
    }
  }
}

Defaults

All fields are optional. Only include the ones you want to change — omitted fields retain their default values. If no flowConfig is provided, all steps are shown normally.

Basic Iframe Setup

The following example shows the complete pattern: build the config, encode it into the iframe URL, and listen for events.

Iframe Element

<iframe
  id="unizo-connect"
  width="480"
  height="700"
  frameborder="0"
  style="border: none;">
</iframe>

Flow Configuration + Event Handling

// 1. Build the flow configuration
var config = {
  flowConfig: {
    attentionInfo: {
      steps: {
        0: {
          title: 'Confirm Admin Access',
          subTitle: 'Your organization requires admin-level access for this integration.',
          options: {
            0: { label: 'Yes, I have admin access' }
          }
        }
      }
    }
  }
};

// 2. Encode and set the iframe URL
var theme = encodeURIComponent(JSON.stringify(config));
var baseUrl = 'https://dock.unizo.ai/links/{serviceKeyId}';
var iframe = document.getElementById('unizo-connect');
iframe.src = baseUrl + '?theme=' + theme;

// 3. Listen for events from the iframe
window.addEventListener('message', function (event) {
  var type = event.data.type;
  var body = event.data.body;

  if (type === 'integration.created') {
    console.log('Integration created:', body.integration.id);
    // Save integration ID to your backend
  }

  if (type === 'connect.close') {
    console.log('Closed, reason:', body.reason);
    iframe.style.display = 'none';
  }
});

Examples

Skip All Pre-Authorization Steps

Bypass all informational steps and go directly to the provider's authorization screen:

var config = {
  flowConfig: {
    attentionInfo: {
      skip: true
    }
  }
};

var theme = encodeURIComponent(JSON.stringify(config));
iframe.src = baseUrl + '?theme=' + theme;

Skip a Specific Step

Skip only the first step while showing all others:

var config = {
  flowConfig: {
    attentionInfo: {
      steps: {
        0: { skip: true }
      }
    }
  }
};

var theme = encodeURIComponent(JSON.stringify(config));
iframe.src = baseUrl + '?theme=' + theme;

Override Step Text

Replace the title and subtitle to match your product's language:

var config = {
  flowConfig: {
    attentionInfo: {
      steps: {
        0: {
          title: 'Admin Access Needed',
          subTitle: 'Please confirm you have administrator privileges before proceeding.'
        }
      }
    }
  }
};

var theme = encodeURIComponent(JSON.stringify(config));
iframe.src = baseUrl + '?theme=' + theme;

Customize and Hide Buttons

Rename the primary button and hide the secondary one:

var config = {
  flowConfig: {
    attentionInfo: {
      steps: {
        0: {
          options: {
            0: { label: 'Confirm & Continue' },
            1: { hide: true }
          }
        }
      }
    }
  }
};

var theme = encodeURIComponent(JSON.stringify(config));
iframe.src = baseUrl + '?theme=' + theme;

Combining with Single Tool Mode

You can combine flowConfig with the serviceId parameter for a fully customized single-service connection flow. This is the most streamlined experience — the user sees only the authorization step for the specified service, with no catalog and no informational steps.

var config = {
  flowConfig: {
    attentionInfo: {
      skip: true
    }
  }
};

var theme = encodeURIComponent(JSON.stringify(config));
iframe.src = baseUrl
  + '?serviceId={serviceId}'
  + '&theme=' + theme;

See Single Tool Mode for details on obtaining the serviceId.

Event Reference

Listen for postMessage events from the iframe to handle integration lifecycle:

Event	When	Key Fields
integration.created	Integration is successfully created (all auth flows)	body.integration.id — the new integration ID
connect.close	User closes the connector modal	body.reason — completed or user_dismissed

Step Indexing

Steps are targeted by their 0-based index in the order they appear in the connection flow. Button options within a step are also 0-indexed.

Index	Typical Content
steps[0]	Primary pre-authorization step (e.g., admin role confirmation)
steps[0].options[0]	Primary action button (e.g., "I am an Admin")
steps[0].options[1]	Secondary action button (e.g., "I'll ask my Admin")

Scope

Detail	Value
Applies to	OAuth and App Install authentication flows
Controls	Pre-authorization steps shown before the user authorizes
Does not affect	Credentials-based flows or post-authorization steps
Applied globally	Configuration applies uniformly across all services

Recommended Iframe Sizing

Viewport	Width	Height	Notes
Desktop	480px	700px	Centered modal card
Tablet	440px	650px	Centered modal card
Mobile	100%	100%	Full screen

---

For additional support, contact our team at [email protected].