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 want | Where |
|---|---|
| Add, edit or remove a connection | Settings › 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 runner | Settings › Integrations › Runners. See Runners. |
| Choose the sources for a question | Ask. 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 brief | Briefs, 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 source | The 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 type | Views on its card |
|---|---|
| MQTT, sensor gateway, GPS telematics, RFID reader | Live sensors, Devices |
| CCTV, video stream, camera | Surveillance |
| Flipper Zero field reader | Field 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:
| Field | Meaning |
|---|---|
id | Server-generated when empty (conn_<nanoseconds>). |
name | Display name. It is never used to decide how a connection behaves. |
type | The connector type, for example snowflake or mqtt. Matching ignores case, spaces, underscores and hyphens. |
environment | Free-form tier label (prod, staging, …). It is not a statement about what stands behind the source. |
runner | Which runner executes work for this connection. See Runners. |
config | A oneof holding one typed configuration message, for example snowflake, mqtt or logistics_api. |
properties | A map<string,string> of extra non-secret settings. Many connectors read fallbacks from it. |
credential_state | Filled by ListConnections (see below). |
source_backing | Filled 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.
CreateConnectionand updates refuse an insecure connection before anything is written, withInvalidArgument:this connection cannot be saved without its security settings: <problems>. - Test.
TestConnectionon a draft that would be refused dials nothing and answersnothing 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.
ListConnectionssetssecurity_okandsecurity_problemson 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_verifyis 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,amqpandplaintext. Usehttps,wss,tls,mqtts,rtsps,ftpsoramqps. - An
ssl_modeofdisable,alloworpreferis refused. - A Kafka
security_protocolofplaintextorsasl_plaintextis refused. - A connector type with no security rule cannot be used.
Rules per connector type:
| Type | What it needs |
|---|---|
| Kafka | security_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, MySQL | ssl_mode stated as require, verify-ca or verify-full (unset is refused), a username and a password credential. |
| MQTT | A tls://, ssl://, mqtts:// or wss:// broker, use_tls on, a username and a password credential. |
| RFID | LLRP over TLS (use_tls, or llrps). The REST protocol needs an https endpoint. |
| GPS telematics | An https endpoint. The nmea provider is refused: it is a raw TCP stream with no encryption. |
| Sensor gateway | Modbus/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. |
| Files | The same as object storage, or an https SharePoint site_url. |
| Salesforce, Guidewire, SAP, Dynamics 365, SharePoint, ServiceNow, logistics APIs, Flipper and Pineapple agents | https addresses. A bare host that the connector would dial as http is refused. |
| CCTV and video | rtsps:// or https:// feeds. A device capture or a video file on the server dials nothing. |
| Web pages | https. A bare address is read as https. |
| BigQuery, Snowflake, HubSpot, GitHub, Google Workspace, Databricks | https by construction. An explicit http:// is refused. |
| Excel, documents | No 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_statetells you what this node holds:Value Meaning 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_backingis covered below.warningscarries 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:
outcome | Meaning |
|---|---|
DELETE_CONNECTION_OUTCOME_DELETED | The credential bundle was removed first, then the record. |
DELETE_CONNECTION_OUTCOME_NOT_FOUND | This instance holds no such id. Nothing was deleted. |
DELETE_CONNECTION_OUTCOME_FAILED | The 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:
success | live_check_performed | Meaning | Typical message |
|---|---|---|---|
| true | true | The connector dialled the source, and the source answered and accepted the credential. | Connectivity verified |
| true | false | The 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 |
| false | true | The probe ran and failed. message is the connector’s own error. | varies (see Troubleshooting) |
| false | false | The 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.
| Value | Meaning | What it does not establish |
|---|---|---|
SOURCE_BACKING_LIVE | Nothing 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_UNSPECIFIED | Not 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/.