Skip to main content
Service accounts require an Enterprise License Key.

​
Overview

Service accounts provide machine-to-machine authentication for automated access to the Lightdash API. Unlike personal access tokens which are tied to individual users, service accounts are organization-level entities designed for applications, CI/CD pipelines, and automated workflows. Service accounts allow you to:
  • Authenticate API requests without using personal user credentials
  • Grant specific permission scopes (read, edit, or admin)
  • Set expiration dates for tokens

​
Enabling service accounts (self-hosted only)

If you’re self-hosting Lightdash, you will need to add the following environment variable to your configuration: 
SERVICE_ACCOUNT_ENABLED=true
After enabling, restart your Lightdash instance for the change to take effect.

​
Creating a Service Account

  1. Navigate to General Settings → Service Accounts
  2. Click Add Service Account New Service Account
  3. Enter a Description and optional Expiry
  4. Select one or more Scopes to grant
  5. Click Create service account
  6. Copy the generated token. This is the only time it will be shown. All service account tokens will be prefixed with ldsvc_

​
Scopes

Scopes are hierarchical - granting a higher-level scope (e.g. org:admin) automatically includes all lower-level permissions (e.g. org:edit, org:view).
ScopeDescription
org:viewRead-only access to Lightdash content.
org:editCan create/modify Lightdash content (charts and dashboards), and all org:view permissions.
org:adminFull organization-level control. Includes deploy, preview, download/upload, user-management, and all org:edit & org:view permissions.

​
Using service accounts

​
With Lightdash CLI

You can use service account tokens to authenticate with the Lightdash CLI: 
lightdash login https://your-lightdash-cloud --token ldsvc_your-token

​
With the API

Service account tokens use the Authorization header: 
curl -H "Authorization: ldsvc_abc123xyz..." \
  "$LIGHTDASH_URL/api/v1/..."
For full API documentation, see the API Reference.

​
Example Use cases

​
CI/CD automation

Use service accounts to automatically deploy dbt changes to Lightdash in your CI/CD pipeline. See deploying with GitHub Actions for implementation details.

​
Instance initialization

When setting up a new self-hosted instance, configure LD_SETUP_SERVICE_ACCOUNT_TOKEN to initialize with a service account. See the environment variables guide for details.

​
Automated reporting

Use service accounts to programmatically export dashboard data, schedule reports, or integrate Lightdash data into other systems via the API.