Connections

Connectors bridge Alomana agents with your external tools — databases, file storage, and applications. They are managed through the Central Hub API and provide agents with secure, credential-managed access to your data.

How Connectors Work

Agent

(message with connection_ids)

metadata

Central Hub

(connector service)

encrypted

PostgreSQL

Snowflake

Slack, ...

You create a connection in the Central Hub, providing credentials for your external service.
Credentials are validated (via a test connection) and encrypted at rest.
When configuring an agent, add connection IDs to enabled_connection_ids.
The agent uses the connection to query data, fetch files, or perform actions on your behalf.

Supported Connectors

Connector	Key	Type	Category	Description
PostgreSQL	`postgresql`	`database`	`data_source`	Query PostgreSQL databases
Snowflake	`snowflake`	`database`	`data_source`	Query Snowflake data warehouses
Google Sheets	`google_sheets`	`file`	`data_source`	Read and analyze spreadsheets
Google Drive	`google_drive`	`file` / `folder`	`data_source`	Access files and folders
Google Calendar	`google_calendar`	`app`	`app`	Read and manage calendar events
Slack	`slack`	`app`	`app`	Send messages, search channels
SharePoint	`sharepoint`	`file` / `folder`	`data_source`	Import selected files and folders into Alo Files
Jira / Confluence	`jira` / `confluence`	`app`	`app`	Search and act on Atlassian content
Salesforce / HubSpot	`salesforce` / `hubspot`	`app`	`app`	Query CRM records
Ironclad / Coupa / OneTrust	`ironclad` / `coupa` / `onetrust`	`app`	`app`	Work with business operations systems
Apollo / Attio	`apollo` / `attio`	`app`	`app`	Work with sales and relationship data
Apify / Tavily	`apify` / `tavily`	`app`	`app`	Web and research tools

Managing Connections

Create a Connection

import httpx

HUB_URL = "https://central-hub.example.com/api/v1"
HEADERS = {"X-API-Key": "sk-your-api-key"}

# PostgreSQL connection
response = httpx.post(
    f"{HUB_URL}/data-sources/connections/",
    headers=HEADERS,
    json={
        "name": "Production Analytics DB",
        "connector_key": "postgresql",
        "auth_type": "basic",
        "credentials": {
            "host": "db.example.com",
            "port": "5432",
            "dbname": "analytics",
            "user": "readonly_user",
            "password": "your-password",
        },
        "category": "data_source",
    },
)
connection = response.json()
print(f"Connection ID: {connection['id']}")

Snowflake Connection

Python

response = httpx.post(
    f"{HUB_URL}/data-sources/connections/",
    headers=HEADERS,
    json={
        "name": "Snowflake Warehouse",
        "connector_key": "snowflake",
        "auth_type": "basic",
        "credentials": {
            "account": "your-account.snowflakecomputing.com",
            "user": "analyst",
            "password": "your-password",
            "warehouse": "COMPUTE_WH",
            "database": "ANALYTICS",
            "schema": "PUBLIC",
        },
        "category": "data_source",
    },
)

OAuth Connections (Google, Slack)

For OAuth-based connectors, the flow is:

Initialize — call the auth init endpoint to get an authorization URL
Redirect — send the user to the authorization URL
Callback — exchange the authorization code for credentials

Python

# Step 1: Start OAuth flow
init_response = httpx.post(
    f"{HUB_URL}/data-sources/connectors/google_drive/auth/init/",
    headers=HEADERS,
    json={"redirect_uri": "https://your-app.example.com/oauth/callback"},
)
auth_url = init_response.json()["auth_url"]
# Redirect user to auth_url...

# Step 2: After user authorizes, handle the callback
callback_response = httpx.post(
    f"{HUB_URL}/data-sources/connectors/google_drive/auth/callback/",
    headers=HEADERS,
    json={
        "code": "authorization-code-from-redirect",
        "state": "state-from-init",
    },
)
credentials = callback_response.json()

# Step 3: Create the connection with the obtained credentials
connection = httpx.post(
    f"{HUB_URL}/data-sources/connections/",
    headers=HEADERS,
    json={
        "name": "My Google Drive",
        "connector_key": "google_drive",
        "auth_type": "oauth2",
        "credentials": credentials,
        "category": "data_source",
    },
)

List Connections

Python

# List all connections
connections = httpx.get(
    f"{HUB_URL}/data-sources/connections/",
    headers=HEADERS,
).json()

# Filter by type
databases = httpx.get(
    f"{HUB_URL}/data-sources/connections/",
    headers=HEADERS,
    params={"category": "data_source", "connector_type": "database"},
).json()

# Filter by connector
slack_connections = httpx.get(
    f"{HUB_URL}/data-sources/connections/",
    headers=HEADERS,
    params={"connector_key": "slack"},
).json()

Execute Queries

You can execute queries directly against a connection:

Python

# SQL query on a database connection
result = httpx.post(
    f"{HUB_URL}/data-sources/connections/{connection_id}/query",
    headers=HEADERS,
    json={
        "query": {"sql": "SELECT * FROM orders LIMIT 10"},
        "timeout_seconds": 30,
    },
).json()

Retrieve Metadata

Fetch the schema (tables, columns, types) of a database connection:

Python

metadata = httpx.post(
    f"{HUB_URL}/data-sources/connections/{connection_id}/metadata",
    headers=HEADERS,
    json={"timeout_seconds": 30},
).json()

for table in metadata["tables"]:
    print(f"Table: {table['name']}")
    for col in table["columns"]:
        print(f"  {col['name']}: {col['data_type']}")

Using Connections with Agents

Once a connection exists, include its ID in the Agent create or update payload:

{
  "enabled_connection_ids": [1],
  "enabled_mcp_connection_ids": []
}

At run time Central Hub checks the caller's space and ownership permissions, resolves credentials, and exposes only the selected connector tools to the agent.

Connector Discovery

You can list all available connectors and their credential requirements:

Python

# List all available connectors
connectors = httpx.get(
    f"{HUB_URL}/data-sources/connectors/",
    headers=HEADERS,
).json()

for c in connectors:
    print(f"{c['name']} ({c['connector_key']}): {c['description']}")

# Get credential fields for a specific connector
fields = httpx.get(
    f"{HUB_URL}/data-sources/connectors/postgresql/credential-fields/",
    headers=HEADERS,
).json()

for field in fields:
    print(f"  {field['name']}: {field['type']} {'(required)' if field['required'] else ''}")

On this page