Connectors Overview

What Is a Connector?

Supported Sources

Data Modes: Sync vs. Live Read

Access modes

Creating a Connector in the Admin Console

1. 1

   Step 1 — Source

   Pick one of four source tiles: REST API, Database, CSV / File, or Webhook. Give the connector a display name, then fill in the per-source config. For a database that means database type, host, port, database, username, password, an optional schema, and a data source choice of Table or Custom SQL Query. This step also carries the Connector Mode choice — Sync (full), Sync (incremental), Live In (Read), or Live In (Read/Write) — which becomes the default mode for every table. For a warehouse there is no choice to make: the panel states that analytics warehouses are read-only and locks the connector to live read.

2. 2

   Step 2 — Discover

   Supero inspects the source and proposes object types for the tables or streams it finds, sampling rows to infer field names and types. It runs as a job with a progress bar, and finishes by handing back a list of proposed schemas plus a suggested namespace. Nothing is created yet. If you named tables on Step 1, only those come back pre-ticked; if you left the table list empty, everything found is ticked.

3. 3

   Step 3 — Review

   The left rail lists the discovered schemas with checkboxes; the right pane has three tabs. Fields lets you rename each column’s target field inline. Identity lets you pick which attributes derive a record’s name, and with which separator — this is what gives a live table a stable primary key. JSON is a read-only preview of exactly what will be saved. Each table also carries its own Data mode control here, so you can override the connector-level choice per table. You must select at least one schema to continue.

4. 4

   Step 4 — Save

   Confirm the auto-generated connector ID (it warns you if it collides with an existing one), the display name, an optional description, and the schema namespace — lower-case, 2 to 24 characters, starting with a letter. Expand Tenant Routing if the source serves more than one of your tenants, and Sync Schedule to pick a cron preset or write your own five-field cron. A summary of endpoint, connector ID, target schema, namespace, schema count, and trigger sits at the bottom. Save creates the connector and its schemas together.

The connection test, and how the table list is populated

Limits worth knowing before you click

• •Selecting more than 100 tables for discovery is rejected with too_many_tables_for_sampled_discovery. Select fewer, or run discovery over the API with infer_from set to "schema", which skips row sampling and scales further.
• •Warehouse discovery samples at most 50 tables in one pass and reports that it capped in the run stats. The console does not surface that number, so on a wide warehouse, name the tables you want.
• •A live table needs an identity. If you set a table to live_read or live_readwrite and no identity fields are chosen, Save refuses and takes you back to the Review step with that table’s Identity tab open. The five HTTP-based warehouses are exempt, because the read planner supplies its own deterministic ordering; Fabric is not exempt.
• •A tenant-routing refusal from the backend is shown as a red list of the exact table and column pairs that caused it, with the single-tenant attestation checkbox directly underneath as the remedy.
• •The schedule panel is hidden when a connector copies nothing — a database connector whose every table is live has nothing to schedule. Flip one table back to sync and it returns.

Source Configuration Reference

Database source config

{
  "plugin": "database",
  "config": {
    "db_type": "postgresql",
    "host": "db.example.com",
    "port": 5432,
    "database": "analytics",
    "schema": "public",
    "username": "reader",
    "password": "REDACTED",
    "query_type": "table",
    "table_names": ["orders"],
    "ssl_mode": "require",
    "batch_size": 1000
  }
}

Warehouse source config

{
  "plugin": "database",
  "config": {
    "db_type": "bigquery",
    "project_id": "my-gcp-project",
    "dataset": "analytics",
    "location": "US",
    "service_account_json": "REDACTED",
    "query_type": "table",
    "table_names": ["orders"]
  }
}

HTTP API source config

{
  "plugin": "http_api",
  "config": {
    "url": "https://api.example.com/data",
    "method": "GET",
    "auth": {
      "type": "api_key",
      "api_key": "YOUR_API_KEY",
      "header_name": "X-API-Key",
      "api_key_location": "header"
    },
    "pagination": { "pagination_type": "offset", "limit": 100 },
    "response": { "data_path": "results", "total_path": "count" }
  }
}

File source config

{
  "plugin": "csv_file",
  "config": {
    "source_type": "s3",
    "s3_bucket": "my-data-bucket",
    "s3_region": "us-east-1",
    "file_path": "exports/users/*.csv",
    "file_format": "csv",
    "csv_delimiter": ",",
    "csv_has_header": true
  }
}

Webhook source config

{
  "plugin": "webhook",
  "config": {
    "auth_type": "signature_hmac",
    "hmac_secret": "REDACTED",
    "hmac_header": "X-Hub-Signature-256",
    "hmac_algorithm": "sha256",
    "hmac_prefix": "sha256=",
    "payload_type": "json",
    "response_mode": "async"
  }
}

Add a Connector Over the API

1. Test the source config

curl -X POST https://api.supero.dev/api/v1/connectors/test-config \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "plugin": "database",
      "config": {
        "db_type": "postgresql",
        "host": "db.example.com",
        "port": 5432,
        "database": "analytics",
        "username": "reader",
        "password": "REDACTED"
      }
    }
  }'

2. Create the connector

curl -X POST https://api.supero.dev/api/v1/connectors \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "orders-db",
    "source": {
      "plugin": "database",
      "config": { "db_type": "postgresql", "host": "db.example.com", "port": 5432, "database": "analytics", "username": "reader", "password": "REDACTED", "query_type": "table", "table_names": ["orders", "customers"] }
    },
    "target": { "tables": [] },
    "trigger": { "type": "manual" },
    "project_uuid": "8f14e45f-2d3a-4b1c-9e6a-1234567890ab"
  }'

3. Run discovery

curl -X POST https://api.supero.dev/api/v1/connectors/{connector_id}/discover \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "streams": ["orders", "customers"], "sample_limit": 100, "timeout_seconds": 300, "infer_from": "samples" }'

# poll:
curl https://api.supero.dev/api/v1/connectors/{connector_id}/discover/{execution_id} \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# then read the proposal:
curl "https://api.supero.dev/api/v1/connectors/{connector_id}/discover/{execution_id}/results?include_samples=true" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

4. Confirm which tables go live

{
  "target": {
    "namespace": "sales",
    "tables": [
      { "schema": "order", "source": "orders", "operation": "upsert", "batch_size": 1000 },
      { "schema": "customer", "source": "public.customers", "mode": "live_read" }
    ]
  }
}

The Control-Plane API

Operating a Connector

Scheduling

Scoping a Live Source by Tenant

{
  "schema": "customer",
  "source": "public.customers",
  "mode": "live_read",
  "live": {
    "tenant_binding": {
      "mode": "column",
      "tenant_field": "org_id",
      "tenant_value_map": { "acme": "42", "globex": "77" },
      "on_unmapped_tenant": "deny"
    }
  }
}

Using Connector-Backed Data in Your App

curl https://api.supero.dev/api/v1/crud/acme-corp/customer?limit=20 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

curl -X POST https://api.supero.dev/api/v1/crud/acme-corp/query \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "type": "customer", "filters": {"org_id": "acme"} }'

import supero

org = supero.connect(domain_name="acme-corp", api_key="ak_...")

# Works the same whether "customer" is a native schema or a live-read connector table
customers = org.crud.list("customer", limit=20)
recent = org.crud.query("customer").filter(org_id="acme").order_by("-created_at").all()

Public Catalog: Zero-Setup Connectors

curl "https://api.supero.dev/api/v1/connectors/catalog?category=Crypto" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Ownership, Status, and Security Posture

Security posture

• •Secrets — database passwords, API keys, warehouse tokens — are stored server-side and are never echoed back in a GET or list response; fields that look like a credential (password, api_key, token, service_account, and similar) are masked before the response reaches your browser. That is also why a config you read back cannot be replayed into test-config.
• •Connection tests and live REST reads only reach publicly routable hosts. Targets that resolve to a private, loopback, link-local, or cloud-metadata address are rejected before any connection is attempted.
• •A source outage on a resolved live binding returns an error (502/503) rather than an empty result set. There is one narrow exception where a live-backed type can return 200 with zero rows without reaching your source — check the access_mode stamp rather than the row count. See Live Data, Read-Only & Security.
• •An unmapped field on a live-read query fails closed with a 4xx error rather than silently dropping a filter or scoping predicate.

Next Steps

• •Database Connectors — the full configuration reference for OLTP sources, incremental sync, and TLS
• •Warehouse Connectors — Snowflake, Databricks, ClickHouse, BigQuery, Redshift, and Fabric, plus the Query console and its cost controls
• •File, HTTP API, Webhook & Public Catalog — the three plugins that need no database driver, including live reads over REST
• •Live Data, Read-Only & Security — the security reference for the live path
• •Connect Your Database — a worked end-to-end example
• •Schema Design — how fields, references, and extends work for the schemas your connectors populate