> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humanintelligence.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SQL API

> Query your governed people data over the Postgres wire protocol from Hex, Streamlit, psql, or any Postgres-compatible client.

The SQL API exposes the same governed metrics, dimensions, and definitions as the [MCP server](/mcp/overview) — 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.

<Info>
  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.
</Info>

## Connection details

Every client uses the same values. Only the username (your email) and the password (your token) are personal.

| Field    | Value                                                   |
| -------- | ------------------------------------------------------- |
| Host     | `sql.humanintelligence.com`                             |
| Port     | `5432`                                                  |
| Database | `analytics`                                             |
| Username | Your Human Intelligence email                           |
| Password | A personal access token (see below)                     |
| SSL mode | `require` (minimum — verifying modes are also accepted) |

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)

<Steps>
  <Step title="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`).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  **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**.
</Tip>

## Creating a personal access token

<Steps>
  <Step title="Go to Connectors → SQL API">
    Open **Connectors** in the left sidebar and click into **SQL API**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Use it as the password">
    In any Postgres client, use your email as the username and the token as the password.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## Connecting from Hex

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  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.
</Note>

## Connecting from psql or Streamlit

```bash psql theme={"dark"}
psql "host=sql.humanintelligence.com port=5432 dbname=analytics user=you@example.com password=<personal_access_token> sslmode=require"
```

```toml Streamlit (.streamlit/secrets.toml) theme={"dark"}
[connections.sql]
type = "sql"
url = "postgresql://you%40example.com:<personal_access_token>@sql.humanintelligence.com:5432/analytics?sslmode=require"
```

<Note>
  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.
</Note>

## 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:

```sql theme={"dark"}
SELECT
  department,
  MEASURE(headcount)      AS headcount,
  MEASURE(attrition_rate) AS attrition_rate
FROM workday_workers
GROUP BY 1
ORDER BY 2 DESC;
```

Prefer `MEASURE()` over re-implementing a metric with `COUNT`/`SUM` yourself: it is the most reproducible path to the same numbers the [MCP tools](/mcp/tools) return, and it uses the definitions your organization has [certified](/platform/metrics).

<Tip>
  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.
</Tip>

## Security and auditing

* **Permissions** — every query runs with the minting user's roles, row-level access, and category permissions. See [Access Control](/governance/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](/governance/audit-log).