Skip to main content
A Data App isn’t limited to sharing inside TextQL. You can embed it directly in your own product, so external users interact with it without ever logging into TextQL. The SDK embed renders the app document and relays compute calls through your backend without creating a chat. For apps where each embedded user should see only their own rows, TextQL supports per-user Row-Level Security (RLS) on the embed: a single app, scoped per session with a short-lived API key tied to that viewer’s identity. The default SDK handler uses a shared API key and does not identify your external users; per-user filtering requires your backend to associate each authenticated user with a session key and use that key for their compute calls.

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’s clientId; 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’s clientId and fail closed when identity is missing:
There’s deliberately no fallback identity here: if the session key has no 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)

A key can only assume roles the minting key already holds. Keep raw SQL disabled for embed sessions so only the governed entrypoints above can run.

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 shared TEXTQL_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

The RefreshApp 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 _tql runtime 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.

Getting support

If you have questions about embedding Data Apps or run into issues, reach out to support@textql.com or visit the customer support page.