Connectors setup guide

This is the hands-on companion to Connectors (the architecture reference) and the individual GUI pages under Administration panel → Integrations. It walks through building one connector end to end, using real screenshots and a real (sanitised) request/response captured while writing this guide.

Two things must exist before you can even save a connector — the order below is enforced by the backend, not just a suggested reading order:

1. The host is on the allowlist. See Connector Allowlist.
2. The credential is stored. See Connector Secrets.

Execution enablement (step 5 below) is the one exception — it can be done last, since it’s checked only at live-execution time, not at save/draft/publish time.

Under Integrations → Allowlist, add the host your connector will call. A Global entry works for every organization; a per-organization entry is scoped to one:

Connector Allowlist

pro-api.coinmarketcap.com added as a Global entry — every organization's connectors can reach it.

If you skip this step, connector save fails outright — verified live:

POST /admin/connectors → 400
"Connector base URL host is not approved for outbound calls.
Ask a platform administrator to add it to the connector allowlist.
(Host 'api.example.com' is not on the allowlist)"

Under Integrations → Credentials, store the API key. Credentials are write-only — the value you paste here is never shown again, only rotated:

Connector Credentials

Name, Organization, Kind, a masked Value, Version, and Status. The connector builder's Credential dropdown only offers entries from this list.

Open Integrations → Connectors → + New connector. The guided builder’s Readiness checklist tracks five conditions; watch it fill in as you go:

Connect step

Organization, Credential, and Operation key resolve as soon as fields are filled. Host on allowlist only turns green after clicking Test connection — typing the URL alone isn't enough.

Two configuration details that are easy to get wrong on the Connect step:

• Scheme — bearer sends Authorization: Bearer <value>. Many providers don’t read that header at all. CoinMarketCap, for example, expects the key in a custom header — get this wrong and you’ll see a live, real failure like the one below, even though the stored credential is perfectly valid.
• Click Test connection — this, not the URL field itself, is what validates the host against the allowlist and flips that checklist item green.

On the Operation step, define the HTTP method and path template, then click Fetch sample to call the live endpoint with the current draft. Here’s the real failure captured while writing this guide — Scheme: bearer, header name Authorization, against an API that expects a raw X-CMC_PRO_API_KEY header instead:

Fetch sample failed: provider_error · HTTP status: 401
Provider returned HTTP 401

Request sent:
GET https://pro-api.coinmarketcap.com/v3/cryptocurrency/listings/latest
accept: application/json
authorization: [REDACTED]

Raw response:
{
  "status": {
    "timestamp": "2026-07-27T18:12:55.297Z",
    "error_code": 1002,
    "error_message": "API key missing.",
    "elapsed": 1,
    "credit_count": 0
  }
}

The fix: set Scheme to raw and Credential header name to the provider’s actual header (X-CMC_PRO_API_KEY in this case). Fetching the sample again succeeds:

HTTP status: 200

Request sent:
GET https://pro-api.coinmarketcap.com/v3/cryptocurrency/listings/latest
accept: application/json
x-cmc_pro_api_key: [REDACTED]

Note what’s sanitised in both cases: the credential value itself is never shown, only [REDACTED] — even in the request echoed back to you while you’re actively debugging your own connector.

With a successful sample fetched, set the Root selector (e.g. $.data[*] for a list endpoint) and click Generate from sample to derive response fields automatically instead of adding them one by one. A trimmed, sanitised example of the real sample fetched above:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  "data": [
    {
      "id": 1,
      "name": "Bitcoin",
      "symbol": "BTC",
      "slug": "bitcoin",
      "circulating_supply": 20062043,
      "max_supply": 21000000,
      "cmc_rank": 1,
      "quote": [
        {
          "symbol": "USD",
          "price": 64909.0311700026,
          "percent_change_24h": 1.52454443,
          "market_cap": 234098182936.80206,
          "last_updated": "2026-07-27T18:13:00.000Z"
        }
      ]
    }
  ]
}

Under Integrations → Connector Execution, both the platform-wide switch and this organization’s rollout inclusion must be on:

Connector Execution Rollout

Everything is off by default. A published, fully-tested connector still won't run for real users until both switches here are on.

Click Publish. The connector is now an immutable version; editing it again creates a new draft without affecting what’s live. A real authenticated call:

POST /connectors/coinmarket_listings/execute
{ "operationKey": "list_latest", "input": {} }

→ 200 OK
{ "rows": [...], "statusCode": 200, "correlationId": "019fa4d0-b420-767b-bd78-05e17f75515d" }

Every one of the calls above — the failed fetch, the successful fetch, and the live execution — is on Connector Audit:

Connector Audit

The live execution (top row) carries no Dry run tag; the builder's Fetch sample / Test response mapping calls below it do. Same audit trail, one tag apart.

Click Details on any row for the full record, including the correlation ID that ties it back to the API response above:

Execution details

Correlation ID 019fa4d0-b420-767b-bd78-05e17f75515d matches the one returned in the execute response — use it to cross-reference a specific call end to end.

Warning

“RLS denial” is not a real connector failure mode — connector execution never touches PostgREST or RLS at all (see Connectors — two data sources). If you’re troubleshooting a page that mixes connector-backed and PostgREST-view-backed elements and only the view-backed ones are empty, that’s a genuine RLS/org-membership issue on the view side — see Capabilities vs Data Scope instead.

If you’re used to promoting an application between environments via Export and Import, note that connector definitions are not currently part of that package format — checked directly against the export/import type definitions and services, which have no connector references at all. Promoting a connector to a new environment today means recreating it there by hand: re-allowlist the host, re-add the credential, and rebuild the connector definition. There’s no single-click promotion path yet.

• Connectors (architecture) — the security model and error-category taxonomy this guide’s troubleshooting table is grounded in.
• Connector Allowlist, Connector Secrets, Connectors, Connector Enablement, Connector Audit — the individual GUI reference pages this guide sequences.
• Capabilities vs Data Scope — the access model connectors follow, and where the “RLS denial” correction above is explained in full.
• Export and Import — application package promotion; does not currently include connectors.