Embedding Ana

​

Service Accounts and API Keys

​

Personal API Keys

• Key name — A label for your reference.
• Expiry seconds — Leave blank for a permanent key, or set a value (e.g., 3600 for one hour) to create a short-lived key.
• Assumed roles — Restrict the key to a subset of your roles. If left blank, the key inherits all of them.

​

Service Accounts

• Name — A descriptive name (e.g., tableau-embed-bot).
• Description (optional) — What this account is for.
• Roles — The roles this account will operate under. These cannot be changed later. If you need different roles, create a new service account.
• Owner — The admin who manages this account.

​

Which Should I Use?

​

The All API Keys View

​

Best Practices

• Use service accounts for production. They are not tied to a person, so they survive role changes and turnover.
• Use expiry seconds to create short-lived keys when possible, especially for embed URLs served to frontends (see Security Best Practices).
• Name everything descriptively. finance-embed-prod is much more useful when auditing six months later.
• Keep service account roles minimal. Only assign what the integration actually needs.
• Revoke unused keys promptly from the All API Keys page.

​

Roles and Assuming Roles from the API

​

How Roles Work

• Every user in TextQL belongs to an organization and can be assigned one or more roles.
• Roles control which connectors (data sources) and context (business rules, definitions) are visible to the user.
• When you create an API key, the key inherits the roles of the user who created it. This means the embedded experience will show exactly the data that user has access to.

​

Context Scoping by Role

​

Assuming a Role via the API

curl 'https://app.textql.com/rpc/public/textql.rpc.public.rbac.RBACService/ListRoles' \
  -H 'Content-Type: application/json' \
  -H 'connect-protocol-version: 1' \
  -H 'Authorization: Bearer YOUR_MASTER_API_KEY' \
  --data-raw '{}'

curl 'https://app.textql.com/rpc/public/textql.rpc.public.rbac.RBACService/CreateApiKey' \
  -H 'Content-Type: application/json' \
  -H 'connect-protocol-version: 1' \
  -H 'Authorization: Bearer YOUR_MASTER_API_KEY' \
  --data-raw '{
    "expirySeconds": 3600,
    "assumedRoles": [
      "80de0196-496f-44fe-9d4c-8013b3b44082",
      "42b3559f-eac2-428c-8def-c8b1847bc84d"
    ]
  }'

{
  "apiKey": "a1b2c3d4-...",
  "apiKeyHash": "ZjBmMDY0ZTEtMTM4Zi00OThjLTk4N..."
}

• apiKey — use as Bearer token for direct API calls (Chat, Stream, etc.)
• apiKeyHash — use in embed URLs (?authKey=HASH)

​

Practical Pattern for Multi-Role Embedding

def get_embed_for_user(user):
    role_map = {
        "finance": ["uuid-for-finance-role"],
        "marketing": ["uuid-for-marketing-role"],
        "executive": ["uuid-for-finance-role", "uuid-for-marketing-role"],
    }

    resp = requests.post(
        "https://app.textql.com/rpc/public/textql.rpc.public.rbac.RBACService/CreateApiKey",
        headers={
            "Content-Type": "application/json",
            "connect-protocol-version": "1",
            "Authorization": f"Bearer {MASTER_KEY}",
        },
        json={
            "expirySeconds": 3600,
            "assumedRoles": role_map[user.role],
        },
    )

    key_hash = resp.json()["apiKeyHash"]
    return f"https://app.textql.com/embed?authKey={key_hash}"

​

Single Sign-On (SSO) and Role Mapping

​

Basic API Use: One-Shot, Streaming, and More

https://app.textql.com/v1

​

Authentication

curl -X POST "https://app.textql.com/v1/chat" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "What were total sales last quarter?"}'

​

Available Endpoints

​

One-Shot Chat (/v1/chat)

{
  "question": "What were total sales last quarter?",
  "chatId": null,
  "tools": {
    "connectorIds": [42],
    "sqlEnabled": true,
    "pythonEnabled": true,
    "ontologyEnabled": true,
    "webSearchEnabled": false
  }
}

• question (required): The natural-language question for Ana.
• chatId (optional): Pass an existing chat ID to continue a conversation. Omit or set to null to start a new chat.
• tools (optional): Configure which tools Ana can use. If omitted, defaults are applied.

{
  "id": "chat-abc123",
  "createdAt": "2026-03-03T12:00:00Z",
  "response": "Total sales last quarter were $4.2M, a 12% increase over the prior quarter...",
  "status": "QUERY_STATUS_COMPLETE"
}

​

Streaming Chat (/v1/stream)

1. Initialize — Create a Connect-RPC transport with your API base URL and auth token.
2. Send request — Send a StreamRequest with your question, optional chat_id, and tools configuration.
3. Receive metadata — The first response contains metadata: chat_id, model, is_continuation, and status.
4. Stream content — Subsequent responses contain incremental text tokens, preview URLs (for charts/images), and tool_call information.
5. Completion — The final response includes status: QUERY_STATUS_COMPLETE.

​

Client SDKs

​

Python SDK

pip install textql

from textql import TextQLClient

client = TextQLClient(api_key="YOUR_API_KEY")

# Configure which tools Ana can use
tools = {
    "connector_ids": [42],
    "sql_enabled": True,
    "python_enabled": True,
    "ontology_enabled": True,
    "web_search_enabled": False,
    "tableau_enabled": False,
    "powerbi_enabled": False,
    "google_drive_enabled": False,
}

stream = client.chat.stream(
    question="Show me revenue by region",
    tools=tools
)

for response in stream:
    if response.HasField('text'):
        print(response.text, end='', flush=True)
    elif response.HasField('metadata'):
        print(f"Chat ID: {response.metadata.chat_id}")
    elif response.HasField('preview'):
        print(f"Preview image: {response.preview.url}")

response = client.chat.create(
    question="What is our current churn rate?",
    tools=tools
)

print(f"Chat ID: {response.id}")
print(f"Response: {response.response}")

​

Tool Configuration Reference

​

Embedding the App via iframe

​

Quick Start

1. Create an API key (see Service Accounts and API Keys above).
2. Construct the embed URL:

https://app.textql.com/embed?authKey=YOUR_API_KEY

3. Test in a browser. Open the URL in an incognito window. You should see a new chat with Ana. If it loads successfully, your API key is working.
4. Add the iframe to your application:

<iframe
  src="https://app.textql.com/embed?authKey=YOUR_API_KEY"
  width="100%"
  height="600px"
  frameBorder="0"
  allow="clipboard-write"
></iframe>

​

Iframe Attributes

​

Embedding in Tableau

1. In Tableau, create a new workbook and add a dashboard.
2. From the Objects panel, drag a Web Page object onto the dashboard.
3. Enter your embed URL: https://app.textql.com/embed?authKey=YOUR_API_KEY
4. Resize the Web Page object to fit your dashboard layout.

​

Embedding in Other BI Tools

• Internal portals (React, Angular, Vue, etc.)
• Confluence / SharePoint (via HTML embed macros)
• Retool / Appsmith (via iframe components)

​

Security Best Practice: Backend Master Key with Short-Lived Frontend Keys

​

The Problem

​

The Recommended Architecture

+-------------------+       +-------------------+       +-------------------+
|                   |       |                   |       |                   |
|   Your Frontend   | ----> |   Your Backend    | ----> |   TextQL API      |
|   (Browser)       |       |   (Server)        |       |                   |
|                   |       |                   |       |                   |
+-------------------+       +-------------------+       +-------------------+
        ^                           |
        |                           |
        +--- short-lived key -------+

1. Store your master API key on your backend server. This is the long-lived key created in TextQL Settings. It never leaves your server.
2. When a user loads your app, your frontend calls your backend to request a session or a short-lived token.
3. Your backend authenticates the user (via your own auth system — SSO, session cookies, JWT, etc.) and determines what role/access level they should have.
4. Your backend generates or proxies the embed URL and returns it to the frontend. The frontend then loads the iframe with the provided URL.
5. Optionally, rotate or scope keys so that each embedded session uses a key with the minimum necessary permissions.

​

Pattern A: Backend Proxy (Most Secure)

Frontend --> Your Backend (authenticated) --> TextQL API (with master key)

​

Pattern B: Short-Lived Scoped Keys (Recommended for Embeds)

@app.route('/api/get-embed-url')
@require_auth
def get_embed_url():
    user_roles = get_textql_role_uuids(current_user)

    resp = requests.post(
        "https://app.textql.com/rpc/public/textql.rpc.public.rbac.RBACService/CreateApiKey",
        headers={
            "Content-Type": "application/json",
            "connect-protocol-version": "1",
            "Authorization": f"Bearer {MASTER_KEY}",
        },
        json={
            "expirySeconds": 3600,  # 1 hour
            "assumedRoles": user_roles,
        },
    )

    key_hash = resp.json()["apiKeyHash"]
    return {"embedUrl": f"https://app.textql.com/embed?authKey={key_hash}"}

• Keys are short-lived (1h recommended) — if leaked, exposure is time-limited
• Each session gets a unique key — easy to audit
• Roles are assigned per-key — no need for separate TextQL user accounts
• No key rotation needed — keys expire on their own

​

Pattern C: Role-Based Key Selection (Alternative)

​

Security Checklist

• API keys are stored server-side only (environment variables, secrets manager, etc.)
• Frontend never contains hardcoded API keys
• Each embed use case has its own dedicated API key
• Keys are rotated on a regular schedule
• Unused keys are revoked promptly
• If using SSO, role mappings are configured so new users get appropriate access automatically
• The iframe uses HTTPS (TextQL enforces this by default)

​

Quick Reference

​

Key URLs

​

API Endpoints Summary

​

Consumption Note