> ## Documentation Index
> Fetch the complete documentation index at: https://lightdash-mintlify-c52c5730.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Enterprise license keys

> Access enterprise features on self-hosted Lightdash instances

<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).
</Note>

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

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.
2. **Receive your license key** — the Lightdash team will share a unique license key with you (typically via 1Password).

## Configuring your license key

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

<Tabs>
  <Tab title="Environment variable">
    ```bash theme={null} theme={null}
    LIGHTDASH_LICENSE_KEY=your-enterprise-license-key-here
    ```
  </Tab>

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

    Then update your deployment:

    ```bash theme={null} theme={null}
    helm upgrade lightdash lightdash/lightdash -n lightdash -f values.yaml
    ```
  </Tab>

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

## License validation and network requirements

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

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

<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.

  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>

No external code is pulled during this process — the request solely validates your license key and returns the validation result.

## Verifying your license

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

1. Logging in as an admin user.
2. Navigating to **Settings → Organization**.
3. Checking for the **Enterprise Edition** badge.

## Enterprise features

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.

### Feature flags

Set these on your Lightdash instance in addition to `LIGHTDASH_LICENSE_KEY`:

| 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)                                         |

### Enterprise SSO providers

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.

| 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)              |

Additional SSO-related options:

* `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 `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)