Skip to main content
Basedash supports two types of embedding:
  • Dashboard embedding: Embed a dashboard as a read-only, interactive view in an iframe.
  • Full app embedding: Embed the full Basedash app (dashboards + chat) inside your product with JWT SSO.

​
Dashboard embedding

Dashboard embedding is best when you want to show a specific dashboard inside another app.

​
Create an embed

  1. Open the dashboard in Basedash
  2. Click Share in the dashboard header
  3. Enable the Embedding toggle
  4. Copy the iframe snippet (or copy the plain URL)
Embeds use a share link with the /shared/{id} path. 
<iframe
	src="https://charts.basedash.com/shared/xyz789"
	width="100%"
	height="600"
	frameborder="0"
	allowfullscreen
></iframe>

​
Show or hide dashboard filters

In the share dialog, you can configure whether dashboard filters are visible in the embed. This is useful when you want a clean, fixed view (hidden filters) versus an explorable view (shown filters).

​
Full app embedding

Full app embedding lets you embed the entire Basedash experience inside your product. Your users can view dashboards, build new charts, and chat with the AI assistant—all without leaving your application. This is ideal for customer portals, partner dashboards, or any scenario where you want to give users a complete BI experience powered by their own data.

​
How it works

Full app embedding uses JWT-based single sign-on (SSO) inside an iframe:
  1. Your server generates a JWT containing the user’s identity and your Basedash organization ID
  2. The iframe loads the SSO endpoint (/api/sso/jwt?jwt=...) with the token
  3. Basedash validates the JWT against your organization’s secret
  4. A session is created for the user (creating their account if needed)
  5. The user is redirected to your organization’s home page inside the iframe

​
Setup overview

Setting up full app embedding involves these steps:
  1. Enable embedding and get your JWT secret
  2. Generate JWTs server-side for your users
  3. Load the iframe with the SSO URL
Full app embedding requires API access. Contact [email protected] to enable the public API for your account.

​
Step 1: Enable embedding

Enable embedding for your organization by going to Settings → Embedding → Enable full app embedding. Once enabled, you can copy your JWT secret from this page. The JWT secret is used to sign tokens that authenticate users into the embedded app.
Store your jwtSecret securely in your environment variables. Never expose it in client-side code.
You can also configure allowed origins on this page to restrict which domains can embed your organization.

​
Step 2: Generate JWTs server-side

Your backend must generate a signed JWT for each user who accesses the embed. Here are examples in common languages: 
import jwt from 'jsonwebtoken';

function generateBasedashToken(user) {
  return jwt.sign(
    {
      email: user.email,
      orgId: process.env.BASEDASH_ORG_ID,
      firstName: user.firstName,
      lastName: user.lastName,
      role: 'MEMBER', // or 'ADMIN'
    },
    process.env.BASEDASH_EMBED_JWT_SECRET,
    { expiresIn: '10m' }
  );
}

// Express route example
app.get('/embed/basedash', (req, res) => {
  const token = generateBasedashToken(req.user);
  const embedUrl = `https://charts.basedash.com/api/sso/jwt?jwt=${token}`;
  
  res.render('embed', { embedUrl });
});

​
Step 3: Load the iframe

In your frontend, render an iframe pointing to the SSO URL: 
<iframe
  src="https://charts.basedash.com/api/sso/jwt?jwt=YOUR_JWT_TOKEN"
  width="100%"
  height="800"
  frameborder="0"
></iframe>

​
JWT claims reference

Your JWT must include these claims:
ClaimTypeRequiredDescription
emailstringYesThe user’s email address
orgIdstringYesYour Basedash organization ID
expnumberYesExpiration timestamp (Unix seconds)
iatnumberYesIssued-at timestamp (Unix seconds)
firstNamestringNoUser’s first name
lastNamestringNoUser’s last name
rolestringNoADMIN or MEMBER (defaults to MEMBER)
The role claim is only used when creating new members. It doesn’t change the role of existing members.

​
Allowed origins

For security, you can restrict which domains can embed your Basedash organization. Configure this at Settings → Embedding If no origins are configured, embeds are allowed from any domain.

​
Security best practices

Never expose the jwtSecret in client-side code. Generate JWTs only on your backend.
JWTs should expire within 10-60 minutes. Users only need a valid token when loading the iframe—once authenticated, they use a Basedash session cookie.
Always set embedAllowedOrigins in production to prevent unauthorized sites from embedding your organization.
When connecting data sources, use database credentials with read-only permissions to minimize risk.
Before generating a JWT, verify that the current user should have access to the embedded analytics.

​
Troubleshooting

Error: “The embed URL is missing the required JWT token”Make sure your iframe src includes the ?jwt= query parameter with your signed token.
Error: “Embedding is not enabled for this organization”Enable embedding when creating the organization by setting fullEmbedEnabled: true, or update an existing organization via the API.
Error: “This embed is not authorized to load from [origin]”Add your domain to the embedAllowedOrigins array. Make sure to include the full origin (e.g., https://app.example.com).
Error: “The JWT token is invalid or has expired”
  • Verify you’re using the correct jwtSecret for the organization
  • Check that the JWT hasn’t expired (tokens should be short-lived)
  • Ensure you’re signing with the HS256 algorithm
  • Verify the clock on your server is accurate (JWT validation allows 30 seconds of clock skew)
Error: “Unable to verify the request origin”This happens when allowed origins are configured but the browser doesn’t send a Referer header. Check that:
  • Your page doesn’t have Referrer-Policy: no-referrer
  • You’re not loading the iframe from a file:// URL during development
Error: “The organization ID in your JWT does not match any Basedash organization”Verify that the orgId claim in your JWT matches an existing Basedash organization ID.