GraphQL Connections
Connections are configured once in the gateway and then called from scripts by name, so credentials and endpoints stay out of your project code.
Table of contents
Configuring a connection
In the Gateway web UI go to Config → Cognidata → GraphQL Connections and add a connection. Each one holds:
| Setting | Notes |
|---|---|
| Name | Unique identifier you reference from scripts (e.g. warehouse-api). |
| Endpoint URL | Fully-qualified GraphQL endpoint, e.g. https://api.example.com/graphql. |
| Auth Type | NONE, BEARER, BASIC, or HEADER. |
| Bearer Token / Basic User+Pass / Header Name+Value | Credentials for the chosen auth type. Secrets are stored encrypted. |
| Custom Headers (JSON) | Optional JSON object of extra headers added to every request, e.g. {"X-Tenant":"acme"}. |
| Timeout (ms) | Per-request timeout. Defaults to 30000. |
| Verify TLS Certificates | Disable only for trusted dev endpoints with self-signed certs. |
Turning off Verify TLS Certificates disables certificate validation for that connection, which exposes it to man-in-the-middle attacks. Use it only against endpoints you control on a trusted network — never in production.
Auth types
| Auth Type | What gets sent |
|---|---|
NONE | No auth header. Use for public endpoints. |
BEARER | Authorization: Bearer <token> |
BASIC | Authorization: Basic <base64(user:pass)> |
HEADER | A single custom header — you supply both the name and the value. Use for APIs that expect e.g. X-API-Key. |
Need more than one extra header? Use Custom Headers (JSON), which is applied on top of whichever auth type you picked:
{"X-Tenant": "acme", "X-Request-Source": "ignition"}
Connection status
The connections table shows a Connection Status column, driven by a background heartbeat that probes each enabled endpoint with { __typename } every 30 seconds:
| Indicator | Meaning |
|---|---|
| 🟢 Online | Last probe succeeded. |
| 🔴 Offline | Last probe failed — the error and how long ago it was checked are shown. |
| ⚪ Disabled / Unknown | The connection is disabled, or hasn’t been probed yet. |
The column reflects the latest probe, so reload the page to refresh it. To check a connection on demand instead of waiting for the heartbeat, use testConnection().
Disabled connections
Clearing Enabled keeps the record but takes the connection out of service:
- The heartbeat stops probing it.
- It disappears from
listConnections(). - Calling it raises
ValueError: GraphQL connection 'x' is disabled.