Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lightdash.com/llms.txt

Use this file to discover all available pages before exploring further.

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 permissions through a system role or a custom role with granular scopes
  • Attribute API actions directly to the service account in audit logs and createdBy / updatedBy fields
  • 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. Choose a System role or assign a Custom role
  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_

​
Rotating tokens

If a service account token is leaked or you want to rotate credentials on a schedule, you can rotate it in place without recreating the service account.
  1. Navigate to General Settings → Service Accounts
  2. Open the ⋯ menu next to the service account and select Rotate token
  3. Choose a new Expiry for the rotated token
  4. Click Rotate token
  5. Copy the new token. As with creation, this is the only time it will be shown.
Rotating a token immediately invalidates the previous token. Update every consumer (CI/CD jobs, deployed services, scripts) before they retry with the old token.
Only service accounts created with an expiry can be rotated. Rotation is rate-limited to once per hour per service account.

​
Permissions

When creating a service account, assign either a system role or a custom role.

​
System roles

Service accounts can be assigned the same organization-level system roles available to users.
RoleDescription
AdminFull organization-level control: manage access and permissions, invite users, create new projects, admin for all projects.
DeveloperView and edit content in all projects, update project connections, create preview projects, use dashboards-as-code (CLI).
EditorView and edit content in all projects.
Interactive ViewerView content in all projects and interact with it (export results, comment, create scheduled deliveries).
ViewerRead-only access to content in all projects.
MemberNo project access by default; granted access on a per-project basis.
For the full permission matrix, see organization roles.

​
Custom roles

For finer-grained permissions, assign a custom role when creating or editing a service account. Custom roles let you pick the exact scopes the service account should have. When a service account is bound to a custom role, the ⋯ menu next to it includes a View custom role link that opens the role definition.
Custom roles are only available on Lightdash Enterprise plans.

​
Legacy scopes

The org:view, org:edit, and org:admin scopes are deprecated. Existing service accounts using these scopes continue to work, but new service accounts should be assigned a system or custom role instead.
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.