Skip to main content
At a Glance: DataBrain uses a stateless token-based architecture that enables secure, multi-tenant embedded analytics. This guide explains the core concepts and architecture patterns.

​
How Embedding Works

DataBrain’s embedding architecture is built on five core components that work together to deliver secure, real-time analytics:

Your Application

Your frontend and backend where dashboards are embedded

DataBrain Platform

Analytics engine that processes queries and renders visualizations

Your Database

Your production database or data warehouse (your data never leaves)

Guest Tokens

Stateless authentication for secure, multi-tenant access

​
Architecture Flow

​
Cloud Deployment

DataBrain Cloud Architecture
When using DataBrain Cloud, the platform hosts the analytics engine while securely connecting to your database:
1

User Logs In

Your user authenticates with your application
2

Generate Token

Your backend requests a guest token from DataBrain API with user context
3

Embed Dashboard

Your frontend receives the token and embeds the DataBrain component
4

Query & Render

DataBrain queries your database directly and streams results to the embedded component
Data Security: Your data never passes through DataBrain’s storage. Queries execute directly against your database, and results stream to the end user.

​
Self-Hosted Deployment

DataBrain Self-Hosted Architecture
With self-hosted deployment, you run the entire DataBrain platform in your own infrastructure:
  • Complete control over data and infrastructure
  • Network isolation - everything stays within your VPC
  • Custom deployment options (single server, HA, multi-region)
  • Air-gapped support for isolated environments

​
Key Architecture Concepts

​
Stateless Guest Tokens

DataBrain uses stateless tokens instead of traditional user authentication: Benefits:
  • ✅ No user data storage - complete privacy
  • ✅ No SSO setup required - integrate in minutes
  • ✅ Multi-tenant isolation built-in
  • ✅ Automatic expiration for security
  • ✅ Tamper-proof cryptographic signatures
How it works: 
// Your backend generates a token
const token = await fetch('https://api.usedatabrain.com/api/v2/guest-token/create', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
  body: JSON.stringify({
    clientId: 'customer-123',
    dataAppName: 'analytics-app'
  })
});

// Your frontend embeds with the token
<dbn-dashboard token={token} dashboard-id="sales" />

​
Multi-Tenant Data Isolation

DataBrain supports N-level tenancy hierarchy (industry-unique):
Route different customers to completely different database servers. Perfect for dedicated database per enterprise customer.
Switch databases based on tenant within the same database server.
Isolate tenants in separate schemas within the same database.
Apply row-level security filters to ensure users only see their data.
-- Example RLS rule
SELECT * FROM orders WHERE customer_id = '{clientId}'

​
Real-Time Query Execution

  1. User interacts with embedded dashboard
  2. Component sends authenticated request
  3. DataBrain validates token and permissions
  4. Generates optimized SQL with RLS applied
  5. Executes directly against your database
  6. Streams results back to user
No data copying - queries run in real-time against your live database.

​
Deployment Options

​
Cloud vs Self-Hosted

Choose the deployment that fits your needs:
Best for:
  • Fast time-to-market
  • Minimal DevOps resources
  • Automatic updates
  • Built-in scalability
How it works:
  • DataBrain hosts the platform
  • Connects securely to your database
  • 99.9% uptime SLA
  • Auto-scaling included
Security:
  • VPC peering available (AWS)
  • IP whitelisting
  • SOC 2, ISO 27001, GDPR compliant
  • Encrypted connections (TLS 1.2+)

​
Security & Compliance

​
Data Protection

Encryption

At Rest: AES-256 encryption for credentialsIn Transit: TLS 1.2+ for all connectionsPasswords: One-way hashing, never stored

Access Control

Token-based: Stateless guest tokensRow-Level: Automatic RLS enforcementPermissions: Fine-grained access control

Network Security

VPC Peering: Private connections (AWS)IP Whitelist: Restrict access by IPDomain Whitelist: Control embedding domains

Compliance

SOC 2 Type II: Security auditsISO 27001: Information securityGDPR & HIPAA: Data protection

​
Best Practices

  • Store API keys in environment variables
  • Never expose keys in frontend code
  • Rotate keys periodically
  • Use separate keys per environment
  • Set reasonable expiration times (1-24 hours)
  • Refresh tokens before expiration
  • Shorter expiry = better security
  • Include RLS rules in token generation
  • Whitelist only necessary domains
  • Remove development domains in production
  • Always use HTTPS in production
  • Review whitelist regularly

​
When to Use What

DataBrain Cloud

Choose when:
  • You want fast deployment
  • You have limited DevOps resources
  • You need automatic scaling
  • You want managed infrastructure
Examples:
  • SaaS startups
  • Small to medium businesses
  • Teams without dedicated DevOps

Self-Hosted

Choose when:
  • You have strict data residency requirements
  • You need complete infrastructure control
  • You operate in air-gapped environments
  • You have specific compliance needs
Examples:
  • Financial institutions
  • Healthcare organizations
  • Government agencies
  • Large enterprises

​
Next Steps

Quick Start

Get your first dashboard embedded in 5 minutes

Production Setup

Complete production deployment guide

Architecture Deep Dive

Detailed technical architecture and implementation

Security Guide

Comprehensive security documentation

​
Common Questions

No. DataBrain only stores metadata like dashboard configurations and metric definitions. Your actual data stays in your database. Queries execute in real-time against your database.
DataBrain supports 4-level tenancy: datasource, database, schema, and row-level. You can route users to different databases or apply row-level security filters - whatever matches your architecture.
Cloud: 99.9% uptime SLA with automatic failover and redundancy.Self-hosted: Availability depends on your infrastructure. You can deploy with high-availability configurations.
Yes! DataBrain supports multi-datasource workspaces. You can route different customers to different databases, even across different database types.
Tokens are cryptographically signed, tamper-proof, and can be configured to expire. They’re validated on every request and include origin checking to prevent unauthorized use.