Skip to main content
🛠 This page is for engineering teams self-hosting their own Lightdash instance. If you want to learn about enterprise features and pricing, go to lightdash.com/pricing.
An enterprise license key unlocks Lightdash Enterprise Edition features on a self-hosted instance. The key on its own enables nothing: each feature has its own environment flag, and you turn on only the ones you use. This page covers getting and applying the key, then each feature — the ones that need a flag or two are enabled right here, and the larger ones (AI agents, data apps, AI writeback, MCP, and pre-aggregates) each have a dedicated setup page linked from their section.

​
Get a license key

  1. Contact the enterprise team — schedule a call to discuss your requirements.
  2. Receive your key — the Lightdash team will share the key with you, typically via 1Password.

​
Apply the license key

Set LIGHTDASH_LICENSE_KEY on every Lightdash container: backend, scheduler, and workers.
Restart every container after adding the key.

​
License validation and network requirements

On server start, Lightdash validates the license key by making an outbound HTTPS request to the Keygen license validation API:
  • Endpoint: https://api.keygen.sh
  • Purpose: validates the key provided in LIGHTDASH_LICENSE_KEY
  • When: on every Lightdash server start
Your Lightdash instance must be able to reach https://api.keygen.sh on server start. This is the only external network request required to run Lightdash with enterprise features. If your environment restricts outbound traffic, allow-list this endpoint in your firewall or proxy.If you also enable the optional organization roadmap, the backend makes outbound requests to https://roadmap.lightdash.com — allow-list that domain too.
No external code is pulled during validation — the request only checks the key and returns the result.

​
Verify the license

After applying the key and restarting:
  1. Log in as an admin user.
  2. Open Settings → Organization.
  3. Confirm the Enterprise Edition badge is present.

​
Features

​
AI agents

AI Analyst and AI agents bring natural-language querying, AI-generated charts, and agents that answer questions in-app and in Slack. Set AI_COPILOT_ENABLED=true and configure a model provider — see AI agents. Every other AI feature below assumes this one is enabled first.

​
Data apps

Data apps are AI-generated React apps, built inside an isolated sandbox and served from an S3-compatible bucket. Set APPS_RUNTIME_ENABLED=true with a sandbox provider, a model provider, and a bucket — see data apps.

​
AI writeback

Beta AI writeback lets an agent edit the dbt repository behind a project and open a pull request with the change. Enable the ai-writeback feature flag and configure the writeback sandbox and its Anthropic key — see AI writeback.

​
MCP

Lightdash can expose a Model Context Protocol server at /api/v1/mcp for AI assistants to query the semantic layer. Set MCP_ENABLED=true — see MCP for connecting assistants and network requirements.

​
Multi-agent Slack channels

Beta Multi-agent Slack channels let one Slack channel host every AI agent in the organization, with the AI Router picking the best-fit agent per question. Requires AI agents and the Slack integration. Set:
Restart the backend, then designate the channel from the AI Agents organization settings — see setting up a multi-agent Slack channel for the in-app steps.

​
Embedding

Embedding renders Lightdash dashboards, charts, data apps, and AI agents inside your own product, authenticated with a JWT signed by an embed secret. Set:
LIGHTDASH_IFRAME_EMBEDDING_DOMAINS is the comma-separated allow-list of origins (protocol included, no trailing slash) permitted to iframe Lightdash — if an embed URL loads on its own but the iframe stays blank, the host origin is missing from this list. Restart the backend, then generate an embed secret from Project settings → Embed configuration. The embedding variables reference covers the optional settings, including the embed event system.

​
Pre-aggregates

Pre-aggregates materialize aggregated tables to S3 and route matching queries to DuckDB instead of your warehouse. They need NATS, an S3-compatible bucket, and a dedicated worker deployment alongside the flag — see pre-aggregates.

​
Custom roles

Custom roles let organization admins define roles with a chosen set of permission scopes, beyond the built-in Admin, Developer, Editor, and Viewer roles. Set:
Restart the backend. Admins can then build and assign roles from Organization settings → Roles.

​
Service accounts

Service accounts are userless, scoped credentials for CLI and API access that outlive their creator. Set:
Restart the backend. Admins can then create and rotate tokens from Organization settings → Service accounts.

​
SCIM

SCIM 2.0 automates user and group provisioning from an identity provider such as Okta, Azure AD, or OneLogin. Set:
When SCIM runs alongside SSO, also set AUTH_ENABLE_OIDC_TO_EMAIL_LINKING=true — without it, Lightdash tries to create a new user on SSO sign-in and fails because the email is already taken by the SCIM-provisioned user. Restart the backend, then follow SCIM integration for the provider-side setup.

​
Enterprise SSO providers

SSO providers such as Google Workspace are available on all plans, but Okta, Azure AD, OneLogin, generic OIDC, Snowflake OAuth, and Databricks OAuth require the license key on self-hosted instances — see Configure SSO for self-hosted Lightdash for the full setup.
For the exhaustive list of environment variables that require an enterprise license key, search “enterprise” on the environment variables reference.

​
Troubleshooting

If enterprise features are unavailable after applying the key:
  1. Confirm LIGHTDASH_LICENSE_KEY is set on every Lightdash container (backend, scheduler, workers).
  2. Confirm every container was restarted after adding the key.
  3. Confirm the per-feature environment flag is set (for example, AI_COPILOT_ENABLED=true for AI Analyst).
  4. Confirm the server can reach https://api.keygen.sh.
  5. Check the Lightdash logs for license-related errors.
  6. Contact enterprise support if the issue persists.

AI agents

Enable AI Analyst and AI agents on a self-hosted Lightdash instance

Data apps

Configure a self-hosted Lightdash instance to run data apps

AI writeback

Enable AI writeback on a self-hosted Lightdash instance

MCP

Enable the Model Context Protocol server on a self-hosted Lightdash instance

Pre-aggregates

Enable pre-aggregate query routing on a self-hosted Lightdash instance