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()

Query Instructions

Query shape is connector-specific — database connectors take raw SQL, while application connectors take a named operation. Fetch the instructions before building a query so you use the right shape and know which operations exist:

Python

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

print(instructions["connector_key"])        # e.g. "snowflake", "google_drive", "slack"
print(instructions["instructions_prompt"])   # how to shape queries for this connector
for action in instructions["actions"]:       # available operations for app connectors
    print(action["key"])

instructions_prompt is authored for Alo's native query tool and may reference tool-only arguments (for example a Google Drive save_results flag) that do not apply to direct HTTP calls. Use it to learn the query shape and the available actions, not as a literal request body.

Execute Queries

You can execute queries directly against a connection. Database connectors take raw SQL under query.sql; application connectors take a named operation under query.operation with the action's parameters alongside it (use instructions above to discover the keys):

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()

# Action query on an application connector (operation + params in the same `query` object)
result = httpx.post(
    f"{HUB_URL}/data-sources/connections/{connection_id}/query",
    headers=HEADERS,
    json={"query": {"operation": "search_messages", "channel": "#sales", "text": "renewal"}},
).json()

The response carries the rows and column metadata, e.g. {"data": [...], "columns": [...]}. Note this is the one connections route with no trailing slash (.../query).

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