Skip to main content
The SQL API exposes the same governed metrics, dimensions, and definitions as the MCP server — over the Postgres wire protocol instead of MCP. Point a BI tool or notebook at it, authenticate with a personal access token, and write SQL against your semantic layer. Permissions are enforced exactly as they are everywhere else in Human Intelligence.
The SQL API is a per-organization feature. It is off until a platform admin enables it under Security & Access Control → SQL API. Until then, the Connectors page shows an Enable button for admins and a contact-your-admin notice for everyone else.

​
Connection details

Every client uses the same values. Only the username (your email) and the password (your token) are personal. The same values are always shown in the app at Connectors → SQL API, along with copy-ready snippets for psql and Streamlit.

​
Enabling the SQL API (platform admins)

1

Open the SQL API policy page

In the left sidebar, open Security & Access Control, then the SQL API tab (app.humanintelligence.com/access/sql-api).
2

Click Enable SQL API

You’ll set the org-wide policy in the same dialog:
  • Default token lifetime — how long a new token lasts if the user doesn’t choose otherwise.
  • Maximum token lifetime — the longest lifetime any user may pick.
  • IP access — either Any IP address or Restrict by IP with a comma-separated list of IP addresses or CIDR ranges.
3

Review active tokens

The same page lists every active token in the organization. Admins can revoke any of them; users can only revoke their own.
Use the IP allowlist. Tokens are the primary credential, but restricting by IP adds a second layer: only listed addresses can even attempt to log in. For hosted tools like Hex, allowlist the egress/gateway IPs the vendor publishes. You can change the policy at any time with Edit Policy.

​
Creating a personal access token

1

Go to Connectors → SQL API

Open Connectors in the left sidebar and click into SQL API.
2

Create a token

Give it a name and, optionally, a lifetime (bounded by the org maximum). The token value is shown once, in an ephemeral modal — copy it now. It cannot be displayed again.
3

Use it as the password

In any Postgres client, use your email as the username and the token as the password.
A token carries the permissions of the user who minted it. If a data admin creates a token and stores it in a shared Hex data connection, everyone with access to that connection queries with the admin’s permissions. Treat token-backed data connections in BI tools as privileged and control who can use them.

​
Connecting from Hex

1

Add a Postgres data connection

In Hex, create a new Postgres data connection. Enter the host, port, and database from the table above, your email as the user, and the token as the password.
2

SSL

Hex doesn’t expose SSL settings; it auto-detects them and verifies against its own trusted roots, so there’s nothing to configure. The server requires TLS (sslmode=require at minimum) and Hex will negotiate verify-full on its own.
3

Wait for discovery

Expect the connection test to spin for up to ~30 seconds while Hex probes SSL settings, then it will run schema/column discovery. This is normal.
Datasets appear in Hex as tables. If a dataset you expect is missing, it’s usually a permissions gap on your Human Intelligence account rather than a connection problem — check with your admin, then refresh the connection’s schema in Hex.

​
Connecting from psql or Streamlit

psql
Streamlit (.streamlit/secrets.toml)
If you use a verifying mode (verify-ca / verify-full) with libpq-based clients such as psql, add sslrootcert=system (libpq 16+) so the client checks against the OS trust store instead of looking for ~/.postgresql/root.crt. Hosted tools like Hex don’t need this.

​
Writing queries

The SQL API speaks the Cube Postgres dialect. Ordinary analytical SQL works — CTEs, aggregates, joins, window functions — and each dataset is exposed as a table whose columns are its dimensions. The important addition is the MEASURE() function, which invokes a governed metric directly:
Prefer MEASURE() over re-implementing a metric with COUNT/SUM yourself: it is the most reproducible path to the same numbers the MCP tools return, and it uses the definitions your organization has certified.
If you’re using an AI assistant inside Hex (or any SQL-generating agent), tell it the connection is Cube Postgres dialect and that governed metrics are called with MEASURE(). It will usually figure this out on its own, but saying so up front gets correct results faster.

​
Security and auditing

  • Permissions — every query runs with the minting user’s roles, row-level access, and category permissions. See Access Control.
  • Revocation — revoking a token (by the user, or org-wide by an admin) terminates any open session using it immediately.
  • Lifetimes — tokens expire on the schedule set by the org policy; expired tokens are rejected at login.
  • IP allowlist — when set, connections from unlisted addresses are refused before authentication.
  • Audit — every SQL API query appears in Audit Logging → Query Audit, tagged with a SQL API source chip so it can be distinguished from MCP traffic and filtered by source. See Audit log.