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

# Enterprise license keys

> Apply a license key to unlock enterprise features on a self-hosted Lightdash instance

<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}
    LIGHTDASH_LICENSE_KEY=your-enterprise-license-key-here
    ```
  </Tab>

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

    Then update your deployment:

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

  <Tab title="Docker Compose">
    ```yaml 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/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](/workspace-admin/custom-roles)                                                                |
| Service accounts                  | `SERVICE_ACCOUNT_ENABLED=true`                     | Machine-to-machine tokens (prefixed `ldsvc_`) with org- or project-scoped roles               | [Service accounts](/workspace-admin/service-accounts)                                                        |
| SCIM provisioning                 | `SCIM_ENABLED=true`                                | Provision and deprovision users and groups from your IdP (Okta, Azure AD, OneLogin, etc.)     | [SCIM integration](/workspace-admin/sso/scim)                                                                |
| AI Analyst / AI agents            | `AI_COPILOT_ENABLED=true`                          | Natural-language querying, AI-generated charts, and AI agents                                 | [AI agents](/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](/agents/set-up-agents#slack-channels-single-agent-vs-multi-agent)               |
| 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](/semantic-layer/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](/embed/reference) · [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](/self-host/data-apps) | AI-generated React apps built in an E2B sandbox and served from an S3 bucket                  | [Data apps self-hosting](/self-host/data-apps)                                                               |
| 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](/agents/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-active-directory) |
| 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)