Skip to content
Connections and credentials

Connections and credentials

You add a connection once, in Settings › Integrations › Systems, and then choose it as a source wherever you ask a question: on Ask, and per brief on Briefs. FACE refuses any connection that would send data or a credential unencrypted.

Where you add and choose connections

What you wantWhere
Add, edit or remove a connectionSettings › Integrations › Systems. New connection opens the connection wizard. A connection that an answer on Ask proposed opens there too, ready to confirm.
Add, edit or remove a runnerSettings › Integrations › Runners. See Runners.
Choose the sources for a questionAsk. Each connection is a card that reads Included in fetch or Not included. An admin can also switch a source Active or Inactive. An inactive source reads Switched off: not read by Fetch.
Choose the sources for a briefBriefs, in the brief’s editor. Each run reads the connections ticked there. With all ticked, it reads every connection, including ones added later. A brief that reads nothing cannot be saved.
Watch a live sourceThe connection’s own card on Ask (see below).

Live connection types have a view of their own. It opens from that connection’s card on Ask, with the connection already chosen:

Connection typeViews on its card
MQTT, sensor gateway, GPS telematics, RFID readerLive sensors, Devices
CCTV, video stream, cameraSurveillance
Flipper Zero field readerField reader, Devices

A view opened from a card shows only that connection, with Show all to widen it.

The rest of this page is reference. A connection is made of two things that are stored apart: a record, which holds settings, and a credential bundle, which holds secrets. The sections below explain how they are split, stored and replicated, what the connection RPCs report, and the security every connection must meet.

The connection record

Connection (in face.proto) carries:

FieldMeaning
idServer-generated when empty (conn_<nanoseconds>).
nameDisplay name. It is never used to decide how a connection behaves.
typeThe connector type, for example snowflake or mqtt. Matching ignores case, spaces, underscores and hyphens.
environmentFree-form tier label (prod, staging, …). It is not a statement about what stands behind the source.
runnerWhich runner executes work for this connection. See Runners.
configA oneof holding one typed configuration message, for example snowflake, mqtt or logistics_api.
propertiesA map<string,string> of extra non-secret settings. Many connectors read fallbacks from it.
credential_stateFilled by ListConnections (see below).
source_backingFilled by ListConnections (see below).

Secrets never stay on the record

Several configuration messages still have secret-looking fields (password, client_secret, personal_access_token, service_account_json, api_key, security_token). When a connection is created, FACE reads those fields, moves them into the credential bundle, and never writes them back out. A connection you read back through ListConnections has those fields empty. That is by design.

Credentials are stored encrypted and never returned by the API. The internal record type has no field that can hold a secret, and secrets placed in the free-form properties map are rejected.

Connectors read their secrets only from the credential bundle they are handed. Setting a password on the record has no effect.

Connection strings

For snowflake and databricks you can paste a connection string in the connection_string property. FACE parses it at save time:

  • The settings it names become typed settings. The string wins for every setting it states. Settings it does not state keep what the form carried.
  • The secret it contains goes to the credential bundle under the connector’s normal key. The raw string itself is not kept.
  • If the string cannot be parsed, the save fails, so you find out when you paste, not at the next fetch.
  • For Snowflake, a DSN field that FACE does not carry is refused rather than dropped silently. So is an explicit host that disagrees with the account.

For other types, a connection_string credential is left in the bundle untouched. The Azure object store reads it from there.

Security requirements

Every connection must use encrypted transport with the server’s certificate checked, and a login wherever the protocol has one. This is not a setting you can turn off. The server enforces it in four places:

  • Save. CreateConnection and updates refuse an insecure connection before anything is written, with InvalidArgument: this connection cannot be saved without its security settings: <problems>.
  • Test. TestConnection on a draft that would be refused dials nothing and answers nothing was dialled: ….
  • Every read of a stored connection. Fetch, Explore, discovery, data listeners, live sensors, document ingest and Test all refuse a stored connection that fails the policy, with FailedPrecondition: this connection is not secured: <problems>; open it in Settings › Integrations and upgrade its security. The stored connection is kept as it is. Nothing rewrites or deletes it.
  • List. ListConnections sets security_ok and security_problems on each connection. The connection wizard opens a refused connection in Upgrade security.

Each problem is one plain sentence that names the setting or credential to fix.

Rules for every connector type:

  • insecure_skip_verify is refused.
  • A cleartext address scheme is refused on every address setting, every Kafka bootstrap server, and every value in properties: http, ws, tcp, mqtt, rtsp, ftp, amqp and plaintext. Use https, wss, tls, mqtts, rtsps, ftps or amqps.
  • An ssl_mode of disable, allow or prefer is refused.
  • A Kafka security_protocol of plaintext or sasl_plaintext is refused.
  • A connector type with no security rule cannot be used.

Rules per connector type:

TypeWhat it needs
Kafkasecurity_protocol sasl_ssl, sasl_mechanism scram-sha-512 or scram-sha-256, a username and a password credential. ssl alone is refused because it carries no login. The CA is optional (empty means the public roots). A Schema Registry, when set, is https with its own schema_registry_username and schema_registry_password.
PostgreSQL, Redshift, MySQLssl_mode stated as require, verify-ca or verify-full (unset is refused), a username and a password credential.
MQTTA tls://, ssl://, mqtts:// or wss:// broker, use_tls on, a username and a password credential.
RFIDLLRP over TLS (use_tls, or llrps). The REST protocol needs an https endpoint.
GPS telematicsAn https endpoint. The nmea provider is refused: it is a raw TCP stream with no encryption.
Sensor gatewayModbus/TCP over TLS (use_tls, port 802), or an https endpoint.
Object storage (S3, GCS, Azure)An https endpoint. A bare S3 host:port needs use_tls.
FilesThe same as object storage, or an https SharePoint site_url.
Salesforce, Guidewire, SAP, Dynamics 365, SharePoint, ServiceNow, logistics APIs, Flipper and Pineapple agentshttps addresses. A bare host that the connector would dial as http is refused.
CCTV and videortsps:// or https:// feeds. A device capture or a video file on the server dials nothing.
Web pageshttps. A bare address is read as https.
BigQuery, Snowflake, HubSpot, GitHub, Google Workspace, Databrickshttps by construction. An explicit http:// is refused.
Excel, documentsNo network transport. A file path that is a URL must be https.

Creating, listing and deleting

Create. CreateConnection takes the Connection and a credentials map. FACE writes the credential bundle first and then the record. If writing the credentials fails, no connection is created, and the response carries success: false with the underlying message. The response echoes connection_id either way, so a retry does not create a second row.

List. ListConnections returns every connection with two annotations and a warnings list:

  • credential_state tells you what this node holds:

    ValueMeaning
    CREDENTIAL_STATE_PRESENTA bundle was found and opened on this node. Nothing was dialled, so an expired password still reads PRESENT.
    CREDENTIAL_STATE_NONE_NEEDEDThe catalogue says this type reads no secret, for example Excel. This is a normal state.
    CREDENTIAL_STATE_ABSENTThere is no bundle for a type that expects one. FACE cannot tell “never entered” apart from “not present on this node”.
    CREDENTIAL_STATE_UNREADABLEA bundle exists and could not be opened. Re-entering the credential does not fix a key problem.
    CREDENTIAL_STATE_UNSPECIFIEDNot computed. This value is not “present” or “absent”.

    The fetch pipeline uses the same classifier, so the list and a fetch always agree. Opening a present bundle is recorded in the credential audit trail.

  • source_backing is covered below.

  • warnings carries plain-language conditions about the list itself, such as storage durability. Show them as written. They are not failures.

Delete. DeleteConnection answers with an explicit outcome:

outcomeMeaning
DELETE_CONNECTION_OUTCOME_DELETEDThe credential bundle was removed first, then the record.
DELETE_CONNECTION_OUTCOME_NOT_FOUNDThis instance holds no such id. Nothing was deleted.
DELETE_CONNECTION_OUTCOME_FAILEDThe delete was attempted and failed. message carries the error, and the connection may still exist. An empty id also returns this, with no connection id provided.

success is true only for DELETED. Deleting a connection does not revoke the credential at its issuer, and it does not rewrite fetch definitions or lineage that reference the id.

Test: what live_check_performed means

ConfigService.TestConnection resolves the connector for the connection’s type:

  • If the connector has a live probe, FACE runs it with the stored credentials.
  • If the connector has no live probe, FACE says so and does not claim a result.

Always read the two booleans together, never the message text:

successlive_check_performedMeaningTypical message
truetrueThe connector dialled the source, and the source answered and accepted the credential.Connectivity verified
truefalseThe configuration is stored. Nothing was verified. The type has no live probe.Configuration saved — a live connectivity check isn't implemented yet for this source type
falsetrueThe probe ran and failed. message is the connector’s own error.varies (see Troubleshooting)
falsefalseThe connection could not be resolved.Connection not found, Unknown connection type "…", could not read the connection: …

A successful probe establishes reachability and credential acceptance, and nothing more. It does not establish any of the following:

  • that a sensor is publishing
  • that an antenna is attached
  • that a probe is calibrated
  • that the credential has scope for any other resource
  • that any records exist

Each connector page lists exactly what its probe does.

Source backing

source_backing states what stands behind a connection on this instance. It is computed from the connection’s address and dials nothing.

ValueMeaningWhat it does not establish
SOURCE_BACKING_LIVENothing that FACE ships stands in for this connection. Whatever it addresses is what it reads.That the source exists, is reachable, or works. A connection to a host that does not exist is still LIVE and simply fails.
SOURCE_BACKING_UNSPECIFIEDNot computed. Every RPC other than ListConnections leaves it unset.Anything about the connection. It is the absence of an answer, not a “live” one.

When a connector fails, the failure is reported as a failure. FACE never substitutes other rows for a failed source. environment is not a substitute for this field: it is a free-form label for the tier of your estate a connection points at, such as “prod” or “staging”.

Storage and replication

  • Records are one replicated snapshot per tenant. FACE stores the snapshot in its own encrypted application filesystem and proposes changes through the platform’s consensus group, so every control-plane replica sees the same set of connections.
  • Credential bundles are rows in the same encrypted store. Each row is sealed under a key derived for FACE and bound to its path. Bundles do not travel on the replication log. Only the record snapshot does.
  • When a fetch runs on a dedicated runner, the control plane reads the bundle once (an audited read). It then seals the bundle to that runner’s in-memory key for that single dispatch. The runner never writes the credential to disk. See Runners.

For the encryption and key model, see /docs/security/.

Observed lineage

Every connector returned by the registry is wrapped by a lineage recorder. Each extraction appends a record to an append-only log. The record contains:

  • column names
  • counts and durations
  • a literal-free query shape and its fingerprint
  • a closed-set error class

A record never contains result values, driver messages or credentials. Camera ingests are recorded separately (one record per ingest, with a row count of zero, because a camera sends frames rather than rows). Lineage is visible in source activity. See /docs/analysis/.