OneAnalytics docs

Embed in your app

Embedded analytics lets you render a OneAnalytics report inside your own product UI. You mint a short-lived JWT on your backend, pass it to the iframe, and OneAnalytics enforces the same permissions, filters, and row-level security rules.

1. Create an embed grant

In the UI: Share → Embed → Create. Pick the report, allowed actions, and an optional filter preset. OneAnalytics generates a client ID and a signing secret — keep the secret server-side.

Via the API:

POST /v1/sharing/grants
{
  "subject_type": "report",
  "subject_id": "<uuid>",
  "principal_type": "embed",
  "actions": ["view"]
}

Response:

{
  "id": "...",
  "embed": {
    "client_id": "emb_01H...",
    "secret_b64": "ZGVtby1zZWNyZXQtLS0..."
  }
}

2. Mint a JWT on your backend

import jwt, time, uuid
token = jwt.encode({
    "iss": "emb_01H...",          # client_id
    "sub": "user_internal_42",     # your user ID
    "exp": int(time.time()) + 600, # 10 minutes
    "jti": str(uuid.uuid4()),
    "oa:user": {
        "email": "ada@example.com",
        "name":  "Ada Lovelace",
        "attributes": {"region": "North"}   # drives RLS
    },
    "oa:filters": {"fiscal_year": 2026}
}, secret, algorithm="HS256")

3. Render the iframe

<iframe
  src="https://embed.analytics.rstglobal.in/r/<report_id>?token=<JWT>"
  style="width:100%; height:600px; border:0;"
  allow="clipboard-write"
></iframe>

Our embed server validates the JWT (signature, expiry, issuer), resolves the grant, and renders the report with the synthetic user's attributes applied to RLS.

Best practices

  • Never ship the signing secret to the browser. Mint JWTs on your backend.
  • Use short TTLs (5-15 min). Browser keeps the iframe alive; if the token expires mid-session, OneAnalytics auto-requests a refresh via postMessage.
  • Implement the oneanalytics:request-token → oneanalytics:token postMessage protocol (sample in TS SDK) to refresh tokens without reloading the iframe.

Theming

Pass theme tokens in the URL: ?theme=dark, ?brand=%230057B7, ?font=Inter. The embedded view uses the same CSS variable system as the main app, so your brand colour flows through.

Security model

  • JWTs are HMAC-SHA256 with your per-grant secret.
  • The jti is checked for replay in Redis for 1 h.
  • CSP headers on our side permit embedding only from domains you've allowlisted in Embed → Settings.