Embed security model

The partner backend is the identity authority. Dataira never asks the browser to prove who the end user is with a reusable server credential.

The public SDK demo follows this model: its API key stays on the demo server and the browser receives only a short-lived token for the exact three-source sample catalog. Its private Company Spend source receives verified identity and policy bindings from the gateway, never from the browser.

SQL evidence visibility

allowSqlEvidence on the token-mint call decides what end users see. The default is true (visible): answers show the assistant's analysis, generated SQL, real conversation titles, and real asset names when the minting key has the embed.sql_evidence.read permission, which runtime keys carry by default.

Mint with allowSqlEvidence: false to hide everything for that session: answers collapse to the neutral placeholder "Analysis complete. Model-authored text and restricted query evidence are hidden by this embed session's evidence policy", and asset names are neutralized. The key permission is the hard gate: without it, evidence is always hidden even when the flag is omitted or true.

Full decision table and exact hidden-session behavior: Backend SDK.

Credential chain

1. Your backend authenticates the end user.
2. It uses an API key scoped to one Project and Environment.
3. It requests a short-lived token for an end-user organization, end user, datasource, and row scope.
4. The browser uses that token with @dataira/react or @dataira/client.
5. The frontend requests a fresh token from your backend when needed.

Scope layers

Layer	Fixed by
Partner / Tenant	API key ownership; emitted as tenant_id
Project and Environment	API key scope
End-user organization and user	Registered membership and token claims
Datasource	Token allowlist plus current access policy
Data slice	Versioned policy; legacy scopeColumn/scopeValue becomes an implicit policy

Collection, preference, conversation, metric, and dashboard operations derive their full Partner/Environment/customer-org/user scope from the token. Their APIs do not accept an arbitrary identity override.

Policy, datasource lifecycle, schema, semantic/PII, API-key, and end-user authorization generations are rechecked at query, stream, cached-result, and finite-response publication boundaries. A stale request fails closed rather than releasing previously authorized evidence.

Partner responsibilities

• Store API keys only in a backend secret manager.
• Authenticate every token endpoint request.
• Derive the end-user and row scope from the authenticated session, not browser input that has not been validated.
• Create separate Environment keys where staging and production must not share credentials, data, or user assets.
• Revoke and rotate keys according to your security policy.

The Node SDK is a convenience layer, not a trust requirement. Any backend can call the token API over HTTPS and keep its own database and identity system.

For a shared customer database, follow the end-user isolation contract and run its required two-user launch test against your production schema. Dataira enforces governed row and column policy; it does not silently install native RLS in your database.