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

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

<Info>
  Service accounts require an **Enterprise License Key**.
</Info>

## 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](/references/workspace/custom-roles) 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:

```bash theme={null}
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**

   <img src="https://mintcdn.com/lightdash-mintlify-ca973f84/Cv-EyrsapF-673yr/images/references/workspace/new-service-account.jpg?fit=max&auto=format&n=Cv-EyrsapF-673yr&q=85&s=5c871c2b466a83d97b3a4648d6f205e1" alt="New Service Account" width="433" height="321" data-path="images/references/workspace/new-service-account.jpg" />
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.

<Warning>
  Rotating a token immediately invalidates the previous token. Update every consumer (CI/CD jobs, deployed services, scripts) before they retry with the old token.
</Warning>

<Info>
  Only service accounts created with an expiry can be rotated. Rotation is rate-limited to once per hour per service account.
</Info>

## 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](/references/workspace/roles#organization-roles).

### Custom roles

For finer-grained permissions, assign a [custom role](/references/workspace/custom-roles) 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.

<Info>
  Custom roles are only available on Lightdash Enterprise plans.
</Info>

### 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:

```bash theme={null}
lightdash login https://your-lightdash-cloud --token ldsvc_your-token
```

### With the API

Service account tokens use the `Authorization` header:

```bash theme={null}
curl -H "Authorization: ldsvc_abc123xyz..." \
  "$LIGHTDASH_URL/api/v1/..."
```

For full API documentation, see the [API Reference](/api-reference/v1/introduction).

## 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](https://docs.lightdash.com/references/dbt-projects#1-automatically%3A-deploy-your-changes-to-lightdash-using-a-github-action) 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](https://docs.lightdash.com/self-host/customize-deployment/environment-variables#initialize-instance) for details.

### Automated reporting

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