Skip to main content

Getting Started with Unizo

Unizo provides multiple integration approaches through MCP, Unified APIs, Connect UI, Connect Agent, and Webhooks to help you build powerful integrations with any third-party service.

This guide walks you through the setup process and helps you select the best approach for your use case.

1

Create your free account

Head over to our Signup page and create your account. Once you've verified your email, you'll be automatically redirected to your dashboard.

For detailed account setup instructions, see our Account Setup Guide.

What you'll get:
  • Access to 3 Unified Integration Categories
  • Free tier with generous limits
  • Full developer console access
  • Technical support
2

Configure Connectors, Webhooks, and API Key in Unizo Console

Enable connectors in the Unizo console by navigating to Setup Integrations, selecting your desired category, and toggling the switch next to any connector.

For detailed instructions, see our Managing Connectors Guide.

Unizo Setup Integrations page showing connector categories

Browse and enable connectors from our expanding catalog

Configure webhooks in the Unizo console by navigating to Setup Integrations, selecting webhooks tab, provide your callback end point where you will receive platform related events.

For detailed instructions, see our Webhooks.

Unizo Setup Integrations page showing webhooks

Browse and configure webhooks

Go to the API Keys page in the Unizo console. For complete API key management, see our API Keys Documentation.

  1. Click "Generate API key"
  2. Give it a descriptive name (e.g., "Production Key")
  3. Copy and securely store your key
API Key Generation

API Key Generation

3

Unizo offers 2 different approaches for managed authentication

Select the approach that best fits your needs and technical requirements :

  • Connect UI: Pre-built UI components for quick integration with minimal coding
  • API-First: Direct API access for complete control and customization
Selected

Connect UI

Quick & Easy

API-First Approach

Full Control

Connect UI Approach

Connect UI provides pre-built, drop-in UI components from Unizo to streamline integration without frontend coding. It supports two modes to cater to different integration needs, offering a secure, ready-made user interface for service authorization.

Connect UI configuration is a one-time process that can be completed directly from the Connect UI section in Unizo Console, generating a unique ID that serves as the DockProfileId for service key generation. For detailed account setup instructions, see our Creating Dock Profile section.

  • Full Experience: Displays a landing widget with all enabled third-party tools and a fully managed authentication workflow.
  • Single Tool Mode: Enables authentication for a specific tool, ideal for customers with custom webpages listing integrations.

Full Experience

In Full Experience mode, Connect UI provides a landing widget showcasing all third-party tools enabled for integration, along with a fully managed authentication workflow. Use the serviceKeys API to generate a service key for embedding the UI.

1

Generate a Service Key

Use your Unizo API key to generate a service key, enabling the Unizo platform to interact with your customer and establish the integration.

Generate Service Key Request
const response = await fetch('https://api.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"
          }
        ]
      }
    },
    "dockProfile": {
      "id": "e0eefe2d-ba39-43fe-a04e-758ccb25ebe2"
    }
  })
});

const data = await response.json();
const serviceKey = data.displayId; // e.g., "197fca710090ef92f23c2d948f1"
const formDescriptorUrl = data.formDescriptorUrl; // e.g., "https://dock.unizo.ai/links/197fca710090ef92f23c2d948f1"
2

Embed Connect UI in Your Application

Use the formDescriptorUrl from the service key response to embed the Connect UI via an iframe, displaying all enabled tools for customer selection.

HTML Implementation
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Connect Your Tools</title>
  <style>
    .integration-wrapper {
      max-width: 1200px;
      margin: 0 auto;
      padding: 2rem;
    }
    .iframe-container {
      width: 100%;
      height: 600px;
      border: none;
      border-radius: 8px;
      box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
    }
  </style>
</head>
<body>
  <div class="integration-wrapper">
    <h1>Connect Your Tools</h1>
    <iframe
      class="iframe-container"
      src="https://dock.unizo.ai/links/197fca710090ef92f23c2d948f1"
      title="Unizo Connect"
      allow="clipboard-write">
    </iframe>
  </div>
</body>
</html>
3

Customer Completes Authentication

The iframe loads a list of pre-selected tools from the Unizo Console. Customers select a tool and complete a secure OAuth flow to authenticate and create the integration.

Single Tool Mode

Single Tool Mode allows authentication for a specific tool, ideal for customers with custom integration listing pages. Retrieve pre-configured tools via the Services API and use the service ID to initiate a targeted authentication flow.

1

Retrieve List of Tools

Use the Services API to fetch pre-configured tools from the Unizo Console for display on your custom integration page.

Fetch Services List
const response = await fetch('https://api.unizo.ai/api/v1/services?limit=20&offset=0', {
  method: 'GET',
  headers: {
    'apikey': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

const services = await response.json();
// Example response
[
  {
    "type": "SCM",
    "id": "6331064d-914c-4a79-a0a7-8bd3896d06e2",
    "name": "GitHub Enterprise",
    "state": "ACTIVE",
    "versions": [
      {
        "type": "SP_VERSION",
        "serviceProfileVersion": {
          "id": "uuid",
          "name": "3.12.0"
        }
      }
    ],
    "accessPointsSummary": {
      "requiresAction": false,
      "readyForConfiguration": 0
    },
    "serviceProfile": {
      "id": "uuid",
      "name": "GitHub Enterprise",
      "image": {
        "original": "https://..."
      },
      "isBeta": true
    },
    "organization": {
      "id": "uuid"
    },
    "attributes": [],
    "tags": [],
    "changeLog": {
      "createdDateTime": "2025-01-17T06:33:14.490+00:00",
      "lastUpdatedDateTime": "2025-01-17T06:33:14.490+00:00"
    }
  }
]
2

Generate a Service Key

When a user selects a tool, generate a service key with the same API call as in Full Experience, using the selected tool’s service ID.

Generate Service Key for Single Tool
const response = await fetch('https://api.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"
          }
        ]
      }
    },
    "dockProfile": {
      "id": "e0eefe2d-ba39-43fe-a04e-758ccb25ebe2"
    }
  })
});

const data = await response.json();
const serviceKey = data.displayId; // e.g., "197fca710090ef92f23c2d948f1"
const formDescriptorUrl = data.formDescriptorUrl; // e.g., "https://dock.unizo.ai/links/197fca710090ef92f23c2d948f1"
3

Embed Connect UI for Single Tool

Embed the Connect UI using an iframe, appending the serviceId query parameter to the formDescriptorUrl to initiate authentication for the selected tool.

Single Tool Mode HTML Implementation
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Connect GitHub Enterprise</title>
  <style>
    .integration-wrapper {
      max-width: 1200px;
      margin: 0 auto;
      padding: 2rem;
    }
    .iframe-container {
      width: 100%;
      height: 600px;
      border: none;
      border-radius: 8px;
      box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
    }
  </style>
</head>
<body>
  <div class="integration-wrapper">
    <h1>Connect GitHub Enterprise</h1>
    <iframe
      class="iframe-container"
      src="https://dock.unizo.ai/links/197fca710090ef92f23c2d948f1?serviceId=6331064d-914c-4a79-a0a7-8bd3896d06e2"
      title="Unizo Connect"
      allow="clipboard-write">
    </iframe>
  </div>
</body>
</html>
4

Customer Completes Authentication

The iframe triggers a guided OAuth flow for the selected tool, creating the integration upon completion.

ℹ️
Important: Service Key Expiration and Integration Creation
  • Service keys are short-lived and expire after 30 minutes.
  • Subsequent calls within the 30-minute window extend the session to 30 minutes from the latest call.
  • Upon completing the authentication flow, an integration is created, represented by an integrationID. An integration:created event is sent to the webhook callback URL configured in the Unizo Console under Platform settings. Use the integrationID in request headers for Unizo’s Unified APIs.

Create Connect UI Link from Console (For Testing Only)

Note: This approach is for testing and proof of concept only. For production, use the API method described above.
1

Configure Webhooks

Configure webhook callback URL to receive integration created events. Read more at Webhooks.

2

Navigate to Connect UI

Go to the Connect UI Section in the Unizo Console.

3

Add Configuration

Click Add Configuration to set up a new Connect UI instance for testing.

  • Name: Unique identifier for the Connect UI instance.
  • Frontend URL: Your branded domain (requires CNAME in DNS).
  • Layout: Choose between Embedded or Pop-up.
4

Test Run Configuration

Select Test Run and provide test parameters:

  • Customer Key: Unique identifier for the customer (required).
  • Customer Name: For internal visibility (optional).
  • Category: Select integration category.
5

Generate URL

Click Generate URL to create a testable Connect UI link.

View Complete Connect UI Documentation Service Keys API Reference
4

Ready to Build?

Now that you understand the approaches, here are your next steps:

🔍 API Explorer

Try our APIs directly in your browser

Open Explorer

💻 SDKs & Libraries

Get started faster with our SDKs

View SDKs

💬 Get Support

Our team is here to help

Contact support@unizo.ai

On this page