Connect UI Integration Guide

Unizo's Connect UI provides a pre-built, secure interface for your users to authenticate with third-party services. This guide covers the production-ready API approach for integrating Connect UI into your application.

Overview

Connect UI handles the complexity of various authentication methods (OAuth 2.0, API keys, etc.) across different service providers, presenting a unified experience to your users.

Key Features

Category-based provider selection - Organize providers by type (SCM, Ticketing, Communications, etc.)
Automatic auth flow handling - OAuth, API keys, and other authentication methods
Secure credential management - No credential handling in your frontend
Responsive design - Works seamlessly across devices
Customizable branding - Match your application's look and feel

Integration Steps

Step 1: Generate a Service Key

Create a service key by making a POST request to the Unizo API. This key establishes a secure session for your user's authentication flow.

Endpoint

POST https://api.unizo.ai/api/v1/serviceKeys

Request Headers

{
  "apikey": "YOUR_API_KEY",
  "Content-Type": "application/json"
}

Request Body

{
  "type": "INTEGRATION_TOKEN",
  "name": "organization-serviceKey",
  "subOrganization": {
    "name": "Acme Inc",
    "externalKey": "68cc5de0-dd15-41c6-9404-18b9cfb3ed3b"
  },
  "integration": {
    "type": "GENERIC",
    "target": {
      "type": "Category",
      "categorySelectors": [
        {
          "type": "SCM"
        }
      ]
    }
  },
  "dockProfile": {
    "id": "e0eefe2d-ba39-43fe-a04e-758ccb25ebe2"
  }
}

JavaScript Example

async function generateServiceKey() {
  try {
    const response = await fetch('https://app.unizo.ai/api/v1/serviceKeys', {
      method: 'POST',
      headers: {
        'apikey': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        "type": "INTEGRATION_TOKEN",
        "name": "organization-serviceKey",
        "subOrganization": {
          "name": "Acme Inc",
          "externalKey": "68cc5de0-dd15-41c6-9404-18b9cfb3ed3b"
        },
        "integration": {
          "type": "GENERIC",
          "target": {
            "type": "Category",
            "categorySelectors": [
              {
                "type": "SCM" // Options: SCM, TICKETING, COMMS, etc.
              }
            ]
          }
        },
        "dockProfile": {
          "id": "e0eefe2d-ba39-43fe-a04e-758ccb25ebe2"
        }
      })
    });

    const data = await response.json();
    return data.serviceKey; // Use this key in your iframe URL
  } catch (error) {
    console.error('Error generating service key:', error);
  }
}

Response

{
  "serviceKey": "196fe56aaae7c00a284dd96452b",
  "expiresAt": "2024-12-31T23:59:59Z",
  "status": "active"
}

Step 2: Embed Connect UI

Use the generated service key to embed Connect UI in your application using an iframe.

HTML Implementation

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Connect Your Tools</title>
  <style>
    .connect-ui-container {
      width: 100%;
      height: 600px;
      border: none;
      border-radius: 8px;
      box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
    }
  </style>
</head>
<body>
  <iframe
    id="unizo-connect-ui"
    class="connect-ui-container"
    src="https://dock.unizo.ai/links/196fe56aaae7c00a284dd96452b"
    frameborder="0"
    allowfullscreen>
  </iframe>
</body>
</html>

React Implementation

import React, { useState, useEffect } from 'react';

function ConnectUI() {
  const [serviceKey, setServiceKey] = useState('');

  useEffect(() => {
    // Generate service key when component mounts
    generateServiceKey().then(key => setServiceKey(key));
  }, []);

  if (!serviceKey) {
    return <div>Loading...</div>;
  }

  return (
    <iframe
      src={`https://dock.unizo.ai/links/${serviceKey}`}
      style={{
        width: '100%',
        height: '600px',
        border: 'none',
        borderRadius: '8px'
      }}
      title="Unizo Connect UI"
      frameBorder="0"
      allowFullScreen
    />
  );
}

Step 3: Handle Authentication Completion

When users complete authentication through Connect UI, they'll be redirected based on your configuration. You can:

Listen for postMessage events from the iframe
Poll the integration status using the Unizo API
Configure webhooks to receive real-time notifications

Example: Listening for postMessage

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://dock.unizo.ai') return;
  
  if (event.data.type === 'AUTH_SUCCESS') {
    console.log('Authentication successful:', event.data.integrationId);
    // Handle successful authentication
  }
  
  if (event.data.type === 'AUTH_ERROR') {
    console.error('Authentication failed:', event.data.error);
    // Handle authentication error
  }
});

Configuration Options

Category Selectors

Specify which categories of providers to display:

Category	Description	Example Providers
`SCM`	Source Code Management	GitHub, GitLab, Bitbucket
`TICKETING`	Issue Tracking	Jira, Linear, Asana
`COMMS`	Communications	Slack, Discord, Teams
`OBSERVABILITY`	Monitoring & Logging	Datadog, New Relic
`VMS`	Vulnerability Management	Snyk, SonarQube

Sub-Organization Configuration

The subOrganization object helps organize integrations by customer:

{
  "subOrganization": {
    "name": "Customer Name",
    "externalKey": "your-unique-customer-id"
  }
}

Security Considerations

API Keys: Never expose your API key in client-side code
Service Keys: Generate new keys for each authentication session
HTTPS Only: Always use HTTPS in production
Domain Validation: Validate postMessage origins

Error Handling

Common error scenarios and solutions:

Error Code	Description	Solution
`401`	Invalid API key	Verify your API key is correct
`403`	Category not enabled	Enable the category in your Unizo dashboard
`422`	Invalid request body	Check required fields in the request
`429`	Rate limit exceeded	Implement exponential backoff

Testing Only – Not for Production

For POCs or internal testing, you can generate Connect UI links through the Unizo Console:

Access the Unizo Console - Log in to app.unizo.ai
Go to Connect UI > Add Configuration
Fill in configuration details:
- Name: Unique identifier for your configuration
- Frontend URL: Your test domain
- Layout: Choose between Embedded or Popup
Use "Test Run" feature:
- Enter a Customer Key (unique identifier)
- Select the desired Category
Click "Generate URL" to get a test Connect UI link

⚠️ Important: This console approach is suitable for POCs or internal testing only. For production environments, always use the API-based approach described above.

Best Practices

Generate service keys server-side - Keep your API key secure
Use meaningful names - Help identify integrations in your dashboard
Handle errors gracefully - Provide clear feedback to users
Test authentication flows - Verify each provider works as expected
Monitor integration health - Use webhooks or polling to track status

Overview​

Key Features​

Integration Steps​

Step 1: Generate a Service Key​

Endpoint​

Request Headers​

Request Body​

JavaScript Example​

Response​

Step 2: Embed Connect UI​

HTML Implementation​

React Implementation​

Step 3: Handle Authentication Completion​

Example: Listening for postMessage​

Configuration Options​

Category Selectors​

Sub-Organization Configuration​

Security Considerations​

Error Handling​

Best Practices​

Next Steps​