Skip to content

Clarify enterprise features and env vars on license keys page #1063

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
12ian34 merged 1 commit into from
Jul 30, 2026
Merged

Clarify enterprise features and env vars on license keys page #1063

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
165 changes: 99 additions & 66 deletions self-host/customize-deployment/enterprise-license-keys.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,107 +1,140 @@
---
title: "Enterprise License Keys"
title: "Enterprise license keys"
description: "Access enterprise features on self-hosted Lightdash instances"
boost: 0.001
---

<Note>
🛠 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](https://lightdash.com/pricing).
🛠 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](https://lightdash.com/pricing).
</Note>

Enterprise License Keys enable access to advanced Lightdash Enterprise Edition features on self-hosted instances. These features include enhanced security, performance optimizations, and advanced collaboration tools designed for large organizations.
Enterprise license keys unlock advanced Lightdash Enterprise Edition features on self-hosted instances — SSO, SCIM, AI agents, embedding, custom roles, service accounts, results caching, pre-aggregates, and more.

## Getting an Enterprise License Key
## Getting an enterprise license key

To obtain an Enterprise License Key for your self-hosted Lightdash instance:
To obtain an enterprise license key for your self-hosted Lightdash instance:

1. **Contact our team** - [Schedule a call with our enterprise team](https://calendly.com/lightdash-cloud/enterprise?utm_source=docs&utm_medium=referral&utm_campaign=enterprise_licensing&utm_content=license_key_page) to discuss your requirements and get your license key.
1. **Contact our team** — [schedule a call with our enterprise team](https://calendly.com/lightdash-cloud/enterprise?utm_source=docs\&utm_medium=referral\&utm_campaign=enterprise_licensing\&utm_content=license_key_page) to discuss your requirements.
2. **Receive your license key** — the Lightdash team will share a unique license key with you (typically via 1Password).

2. **Receive your license key** - Our team will provide you with a unique license key tailored to your organization's needs.
## Configuring your license key

## Configuring Your License Key
Set the license key on every Lightdash container (backend, scheduler, and workers) via the `LIGHTDASH_LICENSE_KEY` environment variable.

Once you have received your Enterprise License Key, you need to configure it in your Lightdash deployment.
<Tabs>
<Tab title="Environment variable">
```bash theme={null}
LIGHTDASH_LICENSE_KEY=your-enterprise-license-key-here
```
</Tab>

### Using Environment Variables
<Tab title="Helm (Kubernetes)">
```yaml theme={null}
secrets:
LIGHTDASH_LICENSE_KEY: your-enterprise-license-key-here
```

Add the following environment variable to your Lightdash configuration:
Then update your deployment:

```bash
LIGHTDASH_LICENSE_KEY=your-enterprise-license-key-here
```
```bash theme={null}
helm upgrade lightdash lightdash/lightdash -n lightdash -f values.yaml
```
</Tab>

### Using Helm (Kubernetes)
<Tab title="Docker Compose">
```yaml theme={null}
services:
lightdash:
environment:
- LIGHTDASH_LICENSE_KEY=your-enterprise-license-key-here
```
</Tab>
</Tabs>

If you're deploying Lightdash on Kubernetes using Helm, add the license key to your `values.yaml` file:
## License validation and network requirements

```yaml
secrets:
LIGHTDASH_LICENSE_KEY: your-enterprise-license-key-here
```
On server start, Lightdash validates your enterprise license key by making an outbound HTTPS request to the [Keygen](https://keygen.sh) license validation API:

Then update your Helm deployment:
* **Endpoint:** `https://api.keygen.sh`
* **Purpose:** validates the license key provided via the `LIGHTDASH_LICENSE_KEY` environment variable
* **When:** on every Lightdash server start

```bash
helm upgrade lightdash lightdash/lightdash -n lightdash -f values.yaml
```
<Note>
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, allowlist this endpoint in your firewall or proxy.

### Using Docker Compose
If you enable the optional [organization roadmap](/self-host/customize-deployment/enable-organization-roadmap), your backend also makes outbound requests to `https://roadmap.lightdash.com` — allowlist that domain too.
</Note>

For Docker Compose deployments, add the license key to your `docker-compose.yml` file:
No external code is pulled during this process — the request solely validates your license key and returns the validation result.

```yaml
services:
lightdash:
environment:
- LIGHTDASH_LICENSE_KEY=your-enterprise-license-key-here
```
## Verifying your license

## License validation and network requirements
After configuring your license key and restarting Lightdash, you can verify that enterprise features are enabled by:

On server start, Lightdash validates your Enterprise License Key by making an outbound HTTPS request to the [Keygen](https://keygen.sh) license validation API:
1. Logging in as an admin user.
2. Navigating to **Settings → Organization**.
3. Checking for the **Enterprise Edition** badge.

- **Endpoint:** `https://api.keygen.sh`
- **Purpose:** Validates the license key provided via the `LIGHTDASH_LICENSE_KEY` environment variable
- **When:** On every Lightdash server start
## Enterprise features

<Note>
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, ensure this endpoint is allowlisted in your firewall or proxy configuration.
A valid enterprise license key unlocks the features below. Most features are gated behind an additional environment variable that you must set to `true` before the feature becomes active. Follow each feature's documentation link for the full list of configuration options.

If you enable the optional [organization roadmap](/self-host/customize-deployment/enable-organization-roadmap), your backend also makes outbound requests to `https://roadmap.lightdash.com` — allowlist that domain too.
</Note>
### Feature flags

No external code is pulled during this process — the request solely validates your license key and returns the validation result.
Set these on your Lightdash instance in addition to `LIGHTDASH_LICENSE_KEY`:

## Verifying your license
| Feature | Environment variable | What it enables | Documentation |
| --------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| Custom roles | `CUSTOM_ROLES_ENABLED=true` | Define custom organization and project roles with granular permissions | [Custom roles](/references/workspace/custom-roles#custom-roles) |
| Service accounts | `SERVICE_ACCOUNT_ENABLED=true` | Machine-to-machine tokens (prefixed `ldsvc_`) with org- or project-scoped roles | [Service accounts](/references/workspace/service-accounts) |
| SCIM provisioning | `SCIM_ENABLED=true` | Provision and deprovision users and groups from your IdP (Okta, Azure AD, OneLogin, etc.) | [SCIM integration](/references/workspace/scim-integration) |
| AI Analyst / AI agents | `AI_COPILOT_ENABLED=true` | Natural-language querying, AI-generated charts, and AI agents | [AI Analyst](/guides/ai-agents) · [env vars](/self-host/customize-deployment/environment-variables#ai-analyst) |
| Multi-agent Slack channels (Beta) | `SLACK_MULTI_AGENT_CHANNEL_ENABLED=true` | Run multiple AI agents in a single Slack channel | [Multi-agent Slack channels](/guides/ai-agents/getting-started#setting-up-a-multi-agent-slack-channel) |
| MCP server | `MCP_ENABLED=true` | Expose Lightdash as an MCP server at `/api/v1/mcp` for AI clients | [MCP integration](/self-host/customize-deployment/configure-mcp-for-lightdash) |
| Results caching | `RESULTS_CACHE_ENABLED=true` | Cache chart and dashboard query results in S3 to skip repeat warehouse queries | [Caching](/guides/developer/caching) · [env vars](/self-host/customize-deployment/environment-variables#cache) |
| Embedding | `EMBEDDING_ENABLED=true` | Embed dashboards, charts, data apps, and AI agents into your own product | [Embedding](/references/embedding) · [env vars](/self-host/customize-deployment/environment-variables#embedding) |
| Pre-aggregates | `preAggregateNatsWorker.enabled: true` | Materialize aggregated tables via a dedicated NATS worker and S3 bucket for faster dashboards | [Pre-aggregate workers](/self-host/nats-workers/pre-aggregate-workers) |
| Data apps | See [self-hosting data apps](/guides/data-apps/self-hosting) | AI-generated React apps built in an E2B sandbox and served from an S3 bucket | [Data apps self-hosting](/guides/data-apps/self-hosting) |
| AI writeback | `ai-writeback` feature flag | Let the AI agent open pull requests against your dbt repo to add or edit metrics | [AI writeback self-hosting](/guides/developer/ai-writeback-self-hosting) |

After configuring your license key and restarting Lightdash, you can verify that enterprise features are enabled by:
### Enterprise SSO providers

1. Logging in as an admin user
2. Navigating to Settings → Organization
3. Checking for the "Enterprise Edition" badge
SSO providers such as Google Workspace are available on all plans. The following SSO providers require an enterprise license key on self-hosted instances. Configure them via environment variables — see [Configure SSO for self-hosted Lightdash](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash) for the full setup guide, and the [SSO env var reference](/self-host/customize-deployment/environment-variables#sso) for all options.

## Enterprise Features
| Provider | Required environment variables | Documentation |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| Okta | `AUTH_OKTA_OAUTH_CLIENT_ID`, `AUTH_OKTA_OAUTH_CLIENT_SECRET`, `AUTH_OKTA_OAUTH_ISSUER`, `AUTH_OKTA_DOMAIN` | [Okta SSO](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash#okta) |
| Azure AD | `AUTH_AZURE_AD_OAUTH_CLIENT_ID`, `AUTH_AZURE_AD_OAUTH_CLIENT_SECRET`, `AUTH_AZURE_AD_OAUTH_TENANT_ID` | [Azure AD SSO](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash#azure-ad) |
| OneLogin | `AUTH_ONE_LOGIN_OAUTH_CLIENT_ID`, `AUTH_ONE_LOGIN_OAUTH_CLIENT_SECRET`, `AUTH_ONE_LOGIN_OAUTH_ISSUER` | [OneLogin SSO](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash#one-login) |
| Generic OpenID Connect | `AUTH_OIDC_CLIENT_ID`, `AUTH_OIDC_CLIENT_SECRET`, `AUTH_OIDC_METADATA_DOCUMENT_URL` | [OpenID Connect](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash#openid-connect) |
| Snowflake OAuth (warehouse sign-in) | `SNOWFLAKE_OAUTH_CLIENT_ID`, `SNOWFLAKE_OAUTH_CLIENT_SECRET`, `SNOWFLAKE_OAUTH_AUTHORIZATION_ENDPOINT`, `SNOWFLAKE_OAUTH_TOKEN_ENDPOINT` | [Snowflake OAuth](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash) |
| Databricks OAuth (warehouse sign-in) | `DATABRICKS_OAUTH_CLIENT_ID`, `DATABRICKS_OAUTH_CLIENT_SECRET`, `DATABRICKS_OAUTH_AUTHORIZATION_ENDPOINT`, `DATABRICKS_OAUTH_TOKEN_ENDPOINT` | [Databricks OAuth](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash) |

With a valid Enterprise License Key, you'll have access to:
Additional SSO-related options:

- **Advanced authentication** - Enhanced SSO options and security controls
- **Extended analytics** - Additional usage analytics and monitoring capabilities
- **Priority support** - Direct access to our enterprise support team
- **Advanced customization** - Additional configuration options for large deployments
- **Performance optimizations** - Features designed for high-scale deployments
* `AUTH_DISABLE_PASSWORD_AUTHENTICATION=true` — recommended for enterprise deployments to force SSO-only sign-in.
* `AUTH_ENABLE_GROUP_SYNC=true` — sync groups from the IdP to Lightdash groups.
* `AUTH_ENABLE_OIDC_TO_EMAIL_LINKING=true` — **required when using SCIM alongside SSO** so SSO sign-ins link to SCIM-provisioned users.

<Tip>
You can [search "enterprise" on the environment variables reference](/self-host/customize-deployment/environment-variables) to see every variable that requires an enterprise license key.
</Tip>

## Troubleshooting

If enterprise features are not available after configuring your license key:

1. Verify the license key is correctly set in your environment variables
2. Ensure Lightdash has been restarted after adding the license key
3. Confirm your server can reach `https://api.keygen.sh` (required for license validation)
4. Check the Lightdash logs for any license-related error messages
5. Contact our [enterprise support team](https://calendly.com/lightdash-cloud/enterprise) for assistance

## Related Documentation

- [Environment Variables Reference](/self-host/customize-deployment/environment-variables)
- [Self-Host Lightdash](/self-host/self-host-lightdash)
- [Lightdash Cloud vs Self-Hosted](/self-host/lightdash-cloud-vs-self-hosted)
1. Verify `LIGHTDASH_LICENSE_KEY` is set on **every** Lightdash container (backend, scheduler, workers).
2. Ensure Lightdash has been restarted after adding the license key.
3. Confirm the corresponding feature flag environment variable is set (for example, `AI_COPILOT_ENABLED=true` for the AI Analyst).
4. Confirm your server can reach `https://api.keygen.sh` (required for license validation).
5. Check the Lightdash logs for any license-related error messages.
6. Contact our [enterprise support team](https://calendly.com/lightdash-cloud/enterprise) for assistance.

## Related documentation

* [Enterprise on-prem setup](/self-host/enterprise-on-prem)
* [Production deployment checklist](/self-host/production-deployment-checklist)
* [Environment variables reference](/self-host/customize-deployment/environment-variables)
* [Configure SSO for self-hosted Lightdash](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash)
* [Self-host Lightdash](/self-host/self-host-lightdash)
* [Lightdash Cloud vs. self-hosted](/self-host/lightdash-cloud-vs-self-hosted)
Loading