Connections
Connect Google Sheets, Drive files, PostgreSQL and OpenAPI sources now; more kinds on request. How Xentropy keeps every read safe.
A connection is an authorized, read-only link to an external data source. Reads from a connection produce datasets, which charts, tables and dashboards bind to.
Source kinds
| Kind | Category | How it authorizes | Reads | Guide |
|---|---|---|---|---|
| PostgreSQL | Database | Username and password over verified TLS | Selected tables and views | PostgreSQL |
| MySQL | Database | Username and password over verified TLS | Selected tables and views | MySQL |
| SQL Server | Database | SQL login, or a Microsoft Entra ID service principal, over verified TLS | Selected tables and views | SQL Server |
| Snowflake | Database & warehouse | Key pair (generated in the browser) | Selected tables and views, using warehouse credits | Snowflake |
| Google BigQuery | Database & warehouse | Service account JSON key | Tables, and SELECT queries under a cost cap | Google BigQuery |
| Shopify | Business app | Dev Dashboard app client credentials, or an Admin API token | Orders, line items, customers, products, variants, inventory | Shopify |
| HubSpot | Business app | Service key (or another read-scoped token) | CRM objects, custom objects, owners, pipeline stages | HubSpot |
| Notion | Business app | Internal Notion connection secret, read content only | Rows of shared databases (data sources) | Notion |
| Git (GitHub, GitLab, Gitea, Bitbucket, Azure DevOps) | Git, Preview | Read-only access token for the forge | Repositories, commits, pull requests, issues, releases, tags, branches, contributors, pipeline runs | Git overview |
| S3-compatible storage | Storage | Access key and secret | Objects or globs: Parquet, Avro, ORC, CSV, TSV, JSON, NDJSON, XML | S3-compatible storage |
| File upload | File | None (your own files) | CSV, TSV, JSON, NDJSON, XML, optionally gzip | File uploads |
| OpenAPI | API | Headers required by the API's security scheme | Selected GET operations, JSON responses | OpenAPI |
| Google Analytics | Analytics | Google consent (read-only) | GA4 reports for selected properties | Google Analytics |
| Google Sheets | Spreadsheet | Google consent | Selected spreadsheets | Google Sheets |
| Google Drive | File | Google consent | Selected CSV and JSON files | Google Drive |
| Raw JSON / CSV | Inline | None | Data you paste or send directly | — |
PostgreSQL, MySQL, SQL Server and Snowflake share one Database entry in
New connection. Choose Database, then choose the engine. Pasting a
connection string selects the engine for you: postgresql://, mysql:// or
mariadb://, an ADO.NET or JDBC SQL Server string, or a
snowflakecomputing.com URL. Switching the engine keeps the connection name
and clears every other field, so a secret typed for one engine is never sent to
another. Pasting a string for the same engine also clears any password or
secret the string does not include, so enter it again for the new server. Only
the engines enabled for your account are listed.
Relations you select after Test and list relations belong to that test. If you then change the connection details, test again before saving: the form keeps your selection and restores every relation the new details can still read.
REST JSON is a legacy kind. Existing REST JSON connections keep working, but you cannot create new ones. Use an OpenAPI connection instead.
Not every kind is generally available yet. On xentropy.ai, MySQL, SQL Server, Snowflake,
S3-compatible storage, file uploads, Shopify, HubSpot, Notion, BigQuery and the
Git forges are enabled on request: contact support@xentropy.ai. Google Analytics is not yet
available on xentropy.ai (coming soon). When a kind is not enabled
for your account, its reads fail with PROVIDER_DISABLED, and retrying does
not help. The New
connection catalogue, and the providers list that agents read, show only the
kinds that are available.
Who can create and read connections
- Each connection belongs to one user. Only that owner can see it.
- In the console, testing or saving credentials may ask you to sign in again.
- An agent needs an API key with
connections:manageto create a connection, and the key must not be restricted to particular connections. Google connections always need the owner's consent in a browser. - An agent can read a source with
connections:reador with that kind's own read scope:postgres:read,mysql:read,sqlserver:read,snowflake:read,s3:read,http:read(OpenAPI and REST JSON),shopify:read,hubspot:read,notion:read,git:read(all Git forges),bigquery:read,sheets:read,drive:readoranalytics:read. - On the Free plan you can have up to 3 connections. Every kind counts, except uploads: uploaded files count toward storage instead.
Security model
Every network connector (PostgreSQL, MySQL, SQL Server, Snowflake, S3-compatible storage, OpenAPI, including OpenAPI specification fetches, and the business app and BigQuery connectors) follows one outbound policy.
Verified TLS, always
- TLS is required. Xentropy checks the certificate chain and requires the certificate to name the host you entered. You cannot turn either check off.
- If your server uses a private certificate authority, paste its CA certificate into the connection form. It is trusted in addition to the public roots, and only for that connection.
- MySQL and SQL Server connections require TLS 1.2 or later. SQL Server uses TDS 8.0 strict encryption when the server supports it.
- Snowflake connections use Snowflake's public certificate only.
Egress pinning and the private-network deny
- Xentropy resolves the hostname once, then checks every address in the answer.
- The connection opens to the exact address that was checked. There is no second lookup, so a DNS answer that changes in the meantime (DNS rebinding) cannot redirect it.
- The TLS server name is always the hostname you entered.
- Xentropy refuses private, loopback, link-local, carrier-grade NAT, benchmark,
documentation, multicast and reserved ranges. For IPv4 these are
0.0.0.0/8,10.0.0.0/8,100.64.0.0/10,127.0.0.0/8,169.254.0.0/16,172.16.0.0/12,192.168.0.0/16,192.0.0.0/24,198.18.0.0/15,224.0.0.0/4and240.0.0.0/4. For IPv6 they are::,::1,fc00::/7,fe80::/10,ff00::/8,2001:db8::/32and IPv4-mapped::ffff:0:0/96. - If a DNS answer mixes public and private addresses, the whole answer is
refused. The error is a
network_policystage error. - Connect to your source's public hostname. Private and internal addresses are never reachable.
- HTTP sources must use HTTPS with no credentials in the URL. Redirects are refused, never followed, so enter the final URL. Each response has a byte limit and a time limit.
- When the policy refuses a connection, the log records only the stage, host and provider. It never records a URL path, query, header or body.
Egress IP addresses
Shopify, HubSpot, Notion and BigQuery connect only to the vendor's own API hosts, and each connector can send only the read requests it needs to those hosts. They need no IP allowlist.
Database, storage and API forms list the outbound IP addresses that Xentropy
connects from, each with a copy button. Allow them in your firewall,
pg_hba.conf, MySQL user host rules, Azure SQL firewall rules, Snowflake
network policies or bucket IP conditions. Agents get the
same list as egressIps from GET /api/v1/data/providers. An empty list means
no fixed addresses are published yet; contact support@xentropy.ai before you
restrict access by IP.
Read-only enforcement
Xentropy enforces read-only access in two places: in Xentropy's own code, and with the least-privilege credentials you create at the source.
| Kind | Enforced by Xentropy |
|---|---|
| PostgreSQL | Every query runs inside BEGIN READ ONLY. Only generated SELECT statements are sent, and identifiers are validated and quoted. |
| MySQL | The session and an explicit transaction are READ ONLY. Multiple statements, LOAD DATA LOCAL and the clear-text password plugin are disabled. |
| SQL Server | Every session runs in a transaction that is always rolled back. Only generated SELECT statements are sent, with bound parameters. |
| Snowflake | Only generated SELECT, SHOW and DESCRIBE statements are sent, one per request (MULTI_STATEMENT_COUNT = 1). The setup SQL creates a SELECT-only role. |
| S3-compatible | The client can only list objects and GET byte ranges. It has no write or delete calls. |
| OpenAPI | Only GET operations can be bound. Pagination cannot leave the bound operation's origin and path. |
The connection requests read-only scopes. Google Analytics uses analytics.readonly. | |
| Shopify | Only Xentropy's own GraphQL read queries are sent, never mutations. |
| HubSpot, Notion | Only listed read endpoints can be called, checked before any connection opens. HubSpot batch reads and Notion search and queries are the only POST requests. |
| Git | Only listed read endpoints on the forge's own host can be called. Azure DevOps work item queries (WIQL) are the only POST requests. Next-page links must stay on the same host and path. |
| BigQuery | Every query is dry-run first and must be a single SELECT. Reads use a read-only token, and every job carries the cost cap. |
The database forms show SQL for a read-only role or user that you can copy and run at the source. The business app and BigQuery forms list the read scopes or roles to grant, with a copy button.
Personal data
Shopify customer contact fields, HubSpot contact properties (name, email,
phone, address) and Notion email, phone and people email fields are marked Personal data in the
field picker. They are off by default. If you select one, the dataset is marked
as containing personal data (containsPii), and agents must confirm it
explicitly. See each guide for the exact fields.
Credentials
- Passwords, secret keys and credential headers are encrypted at rest. They are never returned to the browser or to agents after you submit them.
- When you replace a configuration and leave the secret empty, Xentropy keeps
the stored secret only if the destination and identity have not changed:
- databases: the same host, port, database and user (SQL Server with Entra: the same tenant and client ID; Snowflake: the same account and user);
- S3: the same endpoint, bucket and access key ID;
- OpenAPI: the same server origin, and only for headers that the selected security scheme still requires.
- Disconnecting a credential connection deletes its stored secret.
Disconnect and remove
- Disconnect a connection from its page, or from the ⋯ menu on its card in Connected. Agents lose access at once. The connection moves to the Disconnected view, where you can open it and reconnect.
- Remove permanently a disconnected connection from the ⋯ menu on its card in the Disconnected view. This deletes the connection and its saved settings, removes it from API keys that were limited to it, and can't be undone.
- You can't remove a connection while datasets still read it. The dialog lists those datasets. Delete them, or bind them to another connection, then remove the connection.
- A source shows Not available yet in Browse when it can't be connected yet. Its card has no Connect action until it is available.
- Error messages name only what you typed, such as host, port, database, user or relation. Driver text, resolved addresses and secrets never appear in them.
Read limits
Every read is bounded. A read either returns complete data or fails. Results are never silently truncated.
| Limit | Value |
|---|---|
| Fields per dataset | 100 |
| Rows per read | 50,000 |
| Normalized data per read | 5 MiB |
| Relations listed for a database | 500 |
| Objects listed in a bucket | 5,000 keys |
| Operations in an OpenAPI specification | 1,000 |
| Pages per read (Shopify, HubSpot, Notion, BigQuery) | Free 100, Pro 600 |
| Read deadline (Shopify, HubSpot, Notion, BigQuery) | 30 s interactive, 300 s scheduled |
| BigQuery bytes billed per read | Default 1 GiB, at most 100 GiB |
HubSpot and Notion pages hold 100 records, so on the Free plan their reads
stop at about 10,000 rows. A larger source fails with INCOMPLETE_DATA or
LIMIT_EXCEEDED. Select a
smaller view, prefix or operation, or filter it at the source. Each kind's
page lists its own limits.
Health and recovery
Testing a connection
Test runs the same checks as a save, stage by stage, and reports the first stage that fails:
| Stage | What failed | What to do |
|---|---|---|
dns | The hostname does not resolve | Check the spelling, and use the public hostname |
network_policy | The host resolves to a private or reserved address | Use a public endpoint, or ask your administrator to allow the host |
tcp | Nothing answered on that port | Check the port, and allow Xentropy's egress IPs in the firewall |
tls | TLS is off, or the certificate does not verify for this host | Enable TLS, paste your private CA, or fix the certificate's names |
auth | The credentials or login rules were rejected | Check the user, password, key or host rules |
permission | A selected relation cannot be read | Grant SELECT, or remove the relation from the selection |
warehouse | Snowflake only, on reads: the warehouse cannot run (missing USAGE, or suspended by a resource monitor). The form labels it Compute warehouse | Grant USAGE on the warehouse, or resume it |
Shopify, HubSpot, Notion and BigQuery use the stages auth (the token or key
was rejected) and permissions (a scope or role is missing; missingScopes
names it). BigQuery adds jobs (the service account cannot run query jobs).
Their errors carry the code PROVIDER_ACCESS_DENIED with details.stage.
Database errors are coded POSTGRES_<STAGE>, MYSQL_<STAGE>,
SQLSERVER_<STAGE> or SNOWFLAKE_<STAGE>, for example MYSQL_TLS or
SNOWFLAKE_WAREHOUSE. Object storage has its own stages, such as S3_ACCESS_DENIED.
See S3-compatible storage.
Errors during a read
| Code | Meaning | Retry? |
|---|---|---|
PROVIDER_UNAVAILABLE | The source was unreachable or failed (HTTP 503). details.provider and details.stage say where | Yes, later |
RATE_LIMITED | The source's rate limit or quota is used up. details.retryAt says when to retry, and scheduled refreshes wait until then | After retryAt |
BUDGET_EXCEEDED | The read ran past its time limit | Select less data |
INCOMPLETE_DATA | The source has more than the limits allow, or pagination could not be proven complete | No; narrow the source |
LIMIT_EXCEEDED | A size, row, field or object limit was exceeded | No; narrow the source |
SOURCE_CHANGED | The object or file changed during the read, or after the dataset revision was saved | Yes, or read the current revision |
SCHEMA_CHANGED | The source's fields no longer match the saved definition | Review and save the dataset again |
TYPE_MISMATCH | A value does not match its saved field type | Fix the data or the field's type |
PERMISSION_DENIED | The resource is no longer selected, or the network policy refused the host | Reselect it, or fix the host |
PROVIDER_ACCESS_DENIED | The source denied access: Google Analytics to the property, or a business app or BigQuery to the token, key or scope. details.stage and details.missingScopes say why | No; restore access first |
PROVIDER_PLAN_REQUIRED | The source needs a paid plan or add-on for this data (for example a frozen Shopify store) | No; resolve it at the source |
NOT_FOUND | The source no longer has the resource, or no longer shares it (a Notion database not shared with the connection) | No; restore it at the source |
SOURCE_RESULT_LIMIT | Notion returns at most 10,000 rows for one query, and the data source has more | No; add a filter in Notion |
COST_LIMIT_EXCEEDED | A BigQuery query would bill more than the connection's cap. Nothing was billed | No; narrow the query or raise the cap |
QUERY_NOT_READ_ONLY | A BigQuery query is not a single SELECT | No; rewrite it |
PROVIDER_DISABLED | The kind is not enabled for your account | No; contact support |
CONNECTION_TYPE_UNSUPPORTED | The stored connection is a kind Xentropy can no longer read | No; recreate it |
A read that completes can carry warnings, for example RELATION_TRUNCATED
(Notion), VALUE_TRUNCATED (Notion text over 10,000 characters),
NONFINITE_NULLED (BigQuery NaN) or API_VERSION_MISMATCH (Shopify).
A failed read never replaces earlier data. Live charts keep their previous capture, and the failure shows on the connection and dataset views.
Recovering
- Fix the cause at the source: the firewall rule, certificate, password, grant or bucket policy.
- Open the connection's detail view and choose Replace configuration. Leave the secret empty to keep the stored one (subject to the rules above), then test and save.
- For Google connections, reconnect and approve consent again. For Shopify, HubSpot, Notion and BigQuery, paste a new token, secret or key.
- Refresh the affected datasets or artifacts.
If a connection is in use and you rotate its password, the next read fails at
the auth stage until you replace the configuration.
Folders
Connections can be organised in folders with Move to… on
a connection card. A folder does not change a connection's credentials, access or
what it can read. Agents with data:write or connections:write can move
connections with folders_items_move.