Prerequisites
Set these up before wiring in per-user RLS:- An API key that can create other API keys. Minting a session key per user (step 2 below) is itself a call to the TextQL API made with one master key. A key can always mint keys for its own member, so this needs no key-management permission. The Connector - API permissions (
api_access_key:*) do not apply. See Creating an API Key for how to request one. Keep this key server-side only, so it never reaches the browser. - A dedicated embed role. A key can only mint session keys that assume roles it already holds, so create a role scoped to what an embedded viewer should be able to do, typically read-only, with raw SQL disabled.
- A data entitlement mapping. Row-level scoping only works if there’s already a governed way to resolve a user’s identity to the rows they’re allowed to see (an
access.principal/access.secured_orders-style entrypoint keyed on email, account, or region, for example). This mapping doesn’t have to live in your ontology, and it doesn’t have to sit in the same warehouse as the data it’s scoping — TextQL can join across connectors, so an entitlement table in one warehouse can gate access to data in another. Build the mapping first — the app’s data sources reference it, they don’t create it. - A backend of your own. Mint session keys and host the SDK handler on your backend so API keys stay server-side; your front end talks to that backend.
How it works
Your backend mints a short-lived API key per user session and sets the external identity in the key’sclientId; ana.viewer in compute still identifies the TextQL member that owns the key. Because the key is created server-side, the browser can never choose or forge the identity. For per-user reads, use a compute function that calls ana.query on a governed TQL source reading the session key’s identity.
Step 1: Scope the app’s data sources to the session identity
Write the governed TQL sources used by those compute functions to resolve the external user from the key’sclientId and fail closed when identity is missing:
clientId (or client_attributes_json.username is otherwise blank), access.principal errors and the query returns zero rows rather than reaching for some other identity — a malformed or missing embed session must never see another viewer’s (or the app owner’s) data. Put the entitlements join on every path so no query can reach the underlying table unfiltered.
Step 2: Mint a session key per user (backend only)
Step 3: Embed with the SDK
Follow the SDK embedding quickstart to mount the server handler and render the app in your front end. The quickstart’s default handler uses the sharedTEXTQL_API_KEY; an authorize hook checks access but does not change that credential. For per-user rows, authenticate each request on your backend, retrieve that user’s session key from step 2, and create and invoke a handler for that request with new Textql({ apiKey: <the user's session key secret> }) passed as the client option; do not share that handler across users. If the signed-in user has no session key, refuse the request; never create the client without a defined apiKey, because the SDK then falls back to the shared TEXTQL_API_KEY.
The SDK path creates no chat; its compute calls have a limit described in the SDK guide.
Shared snapshots and refreshes
TheRefreshApp API and scheduled refreshes run declared sources as the app’s creator, subject to caller permission checks for the API; they do not rerun them as each external session user.
Governed compute query results
Security model
- Identity is set once, at key-mint time, on your server, and travels in a signed token the browser cannot read or alter.
- Governed compute queries evaluate the identity in the session key at query time; this does not filter shared snapshot rows in the app document.
- Keys expire on the TTL you choose and can be revoked individually.
- The shared snapshot can contain data from any declared source type. Sources with parameters, a viewer predicate or a grant, and TQL sources that read
_tqlruntime identity are excluded; read them through compute.
Current limitations
- TextQL has no native app-only embed route.
- The SDK element disables deep-link routing and cross-app navigation; an embedded app should hide or disable links to another Data App.
- The default SDK element has no live source-query bridge; use snapshot data and compute calls, with per-user governed reads inside compute functions.