Skip to content

Integrations › Connections

A connection is a record in Runink TIDE’s console registry. It says which external system a tenant’s data lives in, where it is, and which credential bundle unlocks it. The registry is the store/connections package, opened by the console.

TIDE’s records are TIDE’s own. TIDE and the apps share the store/connections package, but each holds separate records. Nothing syncs, mirrors or reconciles TIDE’s registry with an app’s.

Create a connection in the console

Integrations › Connections (rail footer, ?tab=connections) is the only place to create, edit, test and rotate connections. It is the shared datasources wizard (ConnectionsService).

  1. Pick a source card. Cards map to types in the connector catalog. A card whose type the catalog lacks is shown as unavailable.
  2. Fill the settings the type reads. Enter credentials in their own step. Credentials are write-only: no read ever returns them.
  3. Choose the runner that will reach the source. Runink managed is stored as "" (the console process itself). A self-hosted runner is stored by name. See Data-access runners.
  4. Save, then Test. Test is Resolve’s Test, run through the shared estate server on the connection’s bound runner. It is the one dialler, and there is no fallback runner.

Every change, Test and Verify goes through the handler’s own allowlist: TIDE_CONNECTION_ADMINS for connection changes, and TIDE_ATLAS_ADMINS for Test and Verify, because those dial the source. Every attempt is written to the audit chain. See Trust & access.

Resolve’s Add credentials and the onboarding wizard’s Add source open this same wizard.

The JSON registry API

These routes stay available for one release as deprecated aliases. tide connection register still posts to them.

RouteMethodAuth
/api/connection-typesGETsession. The connector catalog: the settings and credential keys each type reads
/api/connectionsGETsession. Lists records. Answers 503, with the full report in the body, when the registry is unreadable
/api/connectionsPOSTadmin-write, TIDE_CONNECTION_ADMINS
/api/connections/{id}GETsession. 404 no connection with id <id> when absent
/api/connections/{id}PUT, DELETEadmin-write, TIDE_CONNECTION_ADMINS

The write body (connectionWrite) is id, name, type, environment, runner, config, properties, credentialRef and credentials. On an update, omitting credentials leaves the stored bundle untouched. The body is capped at 256 KiB. A nested id such as a/b is refused rather than truncated, because the id names a file in the credential store.

The type is canonicalised on write, so Service Now, service-now and servicenow all store as one type. An unrecognised type is stored as-is, because the catalog is a known-types table, not a closed set.

Register connections from a manifest

tide connection register <manifest> applies a committed manifest through the console’s own /api/connections:

export TIDE_CONSOLE_URL=https://<your-console>
export TIDE_CONSOLE_SESSION=<cookie>          # or TIDE_CONSOLE_USER + TIDE_CONSOLE_PASSWORD
export MY_POSTGRES_HOST=… MY_POSTGRES_PASSWORD=…   # from your secret store
tide connection register my-estate.toml --dry-run
FlagEffect
--dry-runvalidate and report what would happen, writing nothing
--adopt-driftoverwrite a console connection whose settings differ from the manifest (off by default: an edited connection is a decision)
--rotate-credentialsreplace the credential bundle of a connection that already exists (off by default, because saving REPLACES)

The console URL comes from --console-url or TIDE_CONSOLE_URL. There is no default. It must be https unless the host is loopback. The session (TIDE_CONSOLE_SESSION, or TIDE_CONSOLE_USER + TIDE_CONSOLE_PASSWORD) is read from the environment only, never from tide.yaml.

Manifest format

A host or an account locator is a fact about one installation’s estate, so keep a real manifest in the repository that owns that estate.

A manifest is a TOML file:

apiVersion = "runink.org/partner-connections/v1"
partner = "template"               # groups the file; documentation only
description = "…"

[[connections]]
id = "template-replace-this-id"    # plain identifier: names a credential file
name = "TEMPLATE — replace this"
type = "postgres"                  # must be in the TARGET console's catalog
environment = "replace-me"

[connections.settings]
host = "${TEMPLATE_POSTGRES_HOST}"
port = 5432                        # never a ${VAR}: numeric settings are refused as strings
database = "${TEMPLATE_POSTGRES_DATABASE}"
username = "${TEMPLATE_POSTGRES_USERNAME}"
ssl_mode = "require"

[connections.properties]
owner = "${TEMPLATE_POSTGRES_OWNER}"

[[connections.credentials]]
key = "username"
fromEnv = "TEMPLATE_POSTGRES_USERNAME"

[[connections.credentials]]
key = "password"
fromEnv = "TEMPLATE_POSTGRES_PASSWORD"
  • ${NAME} resolves inside settings and properties only, from the environment, at apply time. An unresolved reference blocks the connection, which is why applying the template unedited writes nothing.
  • A credential entry has exactly key and fromEnv. Unknown keys are refused when the TOML is decoded, so a value line is a parse error naming its key path, line and column.
  • Declare an ownership property, such as owner or steward, so the data governance agent can name who owns the source.
  • Prefer an ssl_mode of require, verify-ca or verify-full: prefer and allow can fall back to plaintext.

Keeping secrets out of the manifest

The CLI screens every manifest client-side before it writes:

  1. Structural. Unknown fields are parse errors, and a settings key must be a setting that the console’s catalog says the connector reads.
  2. Credential screening. Keys and values are screened for credentials that belong in the credential bundle instead, before and after ${VAR} expansion. What the screen looks for is deliberately not published: a published list tells a reader exactly what it does not catch.
  3. Names, not values. The bundle is assembled from environment variable names at apply time. No error message echoes a value.

Every write is read back and compared.

The report

StateMeaning
CREATEDnothing was there. The record is written, with its bundle if one was declared
UNCHANGEDthe same connection exists. It is not rewritten
DRIFTEDa different connection exists. The differing fields are printed, nothing is written, and the exit code is 1. --adopt-drift overwrites
ADOPTEDa drifted connection was overwritten because --adopt-drift was given
BLOCKEDa declared credential or ${VAR} is unset. Nothing is written, and the missing variable names are printed

Drift is decided before rotation. The console’s PUT writes the record and the bundle in one call, so rotating a drifted connection would adopt the drift.

Two columns are deliberately not answers:

  • NOT CHECKED: registration establishes nothing about reachability, and there is no --verify and must not be one. The CLI never dials. TIDE’s only connector runtime is the console’s Resolve, on an admin’s action, so use Resolve’s Test.
  • NOT REPORTED: whether a bundle is present. Answering that writes a GET_CREDENTIALS audit record per connection.

Connectors TIDE publishes (not registry records)

The platform’s own connectors are configured under POST /api/providers (connectors[]) and published to the connectors. They are not registry records, so Resolve cannot test them. GET /api/connectors/status never dials: it returns the last cached probe, and a connector that was never probed is NOT MEASURED. Only POST /api/connectors/status/refresh dials, and it is admin-write under TIDE_CONNECTION_ADMINS. The types with a probe are databricks, snowflake, mqtt, rfid, sensorgateway, gps, and the REST systems oms, tms, wms, yms, ims and whs. A type with no probe is reported measured:false. POST /api/providers merges by section: an absent or null key keeps what is stored, and "connectors": [] clears it.