Service accounts

Service accounts provide a userless alternative to Personal Access Tokens (PATs) when working with the Lightdash CLI or the API. They are created and managed at the organization level, can be assigned granular scopes, and remain valid even if the administrator who created them leaves the organization.

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

   

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.

Role	Description
Admin	Full organization-level control: manage access and permissions, invite users, create new projects, admin for all projects.
Developer	View and edit content in all projects, update project connections, create preview projects, use dashboards-as-code (CLI).
Editor	View and edit content in all projects.
Interactive Viewer	View content in all projects and interact with it (export results, comment, create scheduled deliveries).
Viewer	Read-only access to content in all projects.
Member	No 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.

Scope	Description
org:view	Read-only access to Lightdash content.
org:edit	Can create/modify Lightdash content (charts and dashboards), and all org:view permissions.
org:admin	Full 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.