Add service accounts documentation (#267)

* Update self-host/customize-deployment/service-accounts.mdx

Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>

* Update docs.json

Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>

* updated & moved zservice account docs

---------

Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
Co-authored-by: Jess Hitchcock <jessica.kaari.hitchcock@gmail.com>

Author: mintlify[bot]

docs.json

@@ -159,6 +159,7 @@
               "references/spaces",
               "guides/pinning",
               "references/personal_tokens",
+              "references/service-accounts",
               "references/personal-warehouse-connections",
               {
                 "group": "Admin",

images/new-service-account.jpg

@@ -3,46 +3,83 @@ title: "Service accounts"
 description: "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 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:
+
+```bash
+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**
 
-   ![Screenshot from 2025-06-20 09-05-15.png](/images/Screenshotfrom2025-06-2009-05-15.png)
-3. Enter a **Description** optional **Expiry**
+   ![New Service Account](/images/new-service-account.jpg)
+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 accounts tokens will be prefixed with `ldsvc_`
-7. Use it to login on the CLI using _``lightdash login https://your-lightdash-cloud --token your-token``_
-8. Or in the API like
-
-```
-GET https://your-lightdash-cloud/api/v1/org/projects
-Authorization: Bearer ldsvc_9649663ed1f1897221da9d8db09b961f
-```
+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`).
+Scopes are hierarchical - granting a higher-level scope (e.g. `org:admin`) automatically includes all lower-level permissions (e.g. `org:edit`, `org:view`).
 
 | Scope       | Description                                                                                                                                   |
 | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `org:admin` | Full organization-level control. Includes deploy, preview, download/upload, user-management, **and** all `org:edit` & `org:view` permissions. |
-| `org:edit`  | Can create/modify Lightdash content (charts and dashboards), **and** all `org:view` permissions.                                              |
 | `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
+lightdash login https://your-lightdash-cloud --token ldsvc_your-token
+```
+
+### With the API
+
+Service account tokens use the `Authorization` header:
+
+```bash
+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.
 
-## Use cases
+### Instance initialization
 
-### I want to create a service account to refresh my dbt changes on Lightdash on CI
+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.
 
-1. Create a service account (see above)
-2. Create a CI pipeline using [github actions](https://docs.lightdash.com/references/dbt-projects#1-automatically%3A-deploy-your-changes-to-lightdash-using-a-github-action)
-3. Make sure you change the `yaml` on github to use your service account token _``lightdash login https://your-lightdash-cloud --token your-token``_
+### Automated reporting
 
-### I want to create a new instance using service accounts
+Use service accounts to programmatically export dashboard data, schedule reports, or integrate Lightdash data into other systems via the API.
 
-1. Follow [this guide to initialize an instance using environment variables](https://docs.lightdash.com/self-host/customize-deployment/environment-variables#initialize-instance)
-2. Make sure you configure the `LD_SETUP_SERVICE_ACCOUNT_TOKEN` (must start with the prefix `ldsvc_`)
-3. Initialize instance
-4. Login on the CLI using this token _``lightdash login https://your-lightdash-cloud --token your-token``_
-5. Update content from templates using `lighdash upload`