Skip to main content

Single Tool Mode

Direct customers to specific connectors with customized activation flows that align with your application workflow

Services API​

The first step is to retrieve a list of tools that are pre-configured via Unizo Console. This is accomplished by making an API call to /services.

Retrieve List of All Services​

Endpoint: GET https://api.unizo.ai/api/v1/services

Retrieves list of all services.

Required Headers​

HeaderTypeRequiredDescription
apikeyStringYesA required access credential for authenticating API requests made to Unizo. The apikey identifies and authorizes the calling integration or service.

Sample 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://...",
        "xSmall": "https://...",
        "small": "https://...",
        "medium": "https://...",
        "large": "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"
    }
  }
]

Implementation​

When you render your webpage with listing of all tools supported, embed serviceID for each tool in UI components so that when a user clicks one of the tools integrated through Unizo, its serviceID can be passed as a query parameter.

Service Keys API​

When a user clicks on one of the tools listed, make an API call to /serviceKeys to start a session.

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

Required Headers​

HeaderTypeRequiredDescription
apikeyStringYesA required access credential for authenticating API requests made to Unizo. The apikey identifies and authorizes the calling integration or service.

Sample Request Payload​

{
  "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"
  }
}

Embedding the Connect UI in Your Frontend​

To initiate the service authentication flow directly within your application, embed the Connect UI using an iframe. The value of the src attribute should be set to the value of the formDescriptorUrl field received in the response of the API above, with the serviceID query parameter appended to identify the specific tool the customer wants to integrate with.

Example Implementation​

<!DOCTYPE html>
<html lang="en">
<!-- ... -->
<body>
  <iframe
    class="iframe-container"
    src="https://dock.unizo.ai/links/196fe56aaae7c00a284dd96452b?serviceId=6331064d-914c-4a79-a0a7-8bd3896d06e2"
    frameborder="0"
    allowfullscreen>
  </iframe>
</body>
</html>

Query Parameters​

ParameterTypeRequiredDescription
serviceIdUUIDYesA required query parameter that uniquely identifies the target service or provider the customer is expected to authenticate with. This ID is obtained from the Service API and determines which integration flow will be initiated within the Connect UI

Integration Flow​

When the iframe loads, it triggers the guided flow for authentication and creation of integration.

For additional support, contact our team at support@unizo.ai.