# Service User Best Practices

Source: https://userguide.qualytics.io/settings/access/service-users/deep-dive/best-practices/

Follow these guidelines to keep your Service Users secure and well-managed. This page focuses on Service User account management; for Service Token security and expiration strategy, see [Service Token Best Practices](https://userguide.qualytics.io/settings/access-tokens/service-token/deep-dive/best-practices/).

## Key Takeaways

### Use Service Users for Production Integrations

- Operate independently of individual users, their access changes, or lifecycle events
- Centrally managed by administrators for consistency and control
- Provide clear, purpose-based audit trails
- Strengthen overall security posture

### Administrator Responsibilities

- Create, manage, and maintain Service Users.
- Review Service User activity and deactivate decommissioned accounts.
- Maintain documentation for each Service User's purpose and ownership.
- Ensure role and team assignments remain appropriate over time.

## Naming Conventions

Use descriptive names that indicate the Service User's purpose. This makes it easier to identify and manage multiple accounts.

The system auto-generates an internal ID from the name using the following rules: lowercase letters, spaces converted to underscores, and special characters removed. The ID is suffixed with `@service`.

**Example:** `Pipeline Automation` → `pipeline_automation@service`

- Yes `Pipeline Automation` — For automated ETL workflows.
- Yes `Alation Sync` — For metadata synchronization with Alation.
- Yes `API Access` — For programmatic API interactions.
- No `test` — Not descriptive enough.
- No `service1` — Too generic.
- No `my-service` — Unclear purpose.

## Role Assignment

Apply the **Least Privilege Principle** when assigning a role to a Service User:

- Grant only the minimum role required for the integration's use case.
- For example, a metadata sync integration limited to selected datastores only needs the **Member** role with the **Editor** team permission on those datastores. Starting a full sync needs the **Manager** role, and the sync still skips datastores where the user lacks the **Editor** team permission.
- Avoid assigning **Admin** unless the integration legitimately requires full platform control.
- Document justification whenever an elevated role (Manager, Admin) is assigned.

## Team Scope

Restrict team membership to the datastores and resources the Service User actually needs:

- The **Public** team is automatically included for all Service Users.
- Assign additional teams only when the integration requires access to specific datastores.
- Avoid broad team assignments — they increase the blast radius if a token is compromised.
- Review team memberships periodically and remove unused ones.

## Account Lifecycle

- Deactivate Service Users whose integration has been decommissioned or replaced.
- Review existing Service Users periodically (quarterly recommended) to identify unused accounts.
- Preserve deactivated Service Users for audit purposes; reactivate if the integration resumes.
- Document the reason and date whenever a Service User is created, updated, or deactivated.

## Documentation and Ownership

Treat each Service User as a tracked asset:

- Assign a **human owner** or team responsible for the Service User.
- Document the **purpose** — which integration, pipeline, or workflow the Service User serves.
- Keep a record of **creation date** and **last review date**.
- Update documentation when ownership transfers or the integration changes scope.

## When to Use Service Users vs Personal Accounts

| Scenario | Use |
| --- | --- |
| Production pipelines and automation | Service User |
| Data catalog integrations | Service User |
| Shared automation across teams | Service User |
| CI/CD pipelines (long-lived) | Service User |
| Personal development and testing | Personal Account |
| Ad-hoc API exploration | Personal Account |
| Qualytics CLI (personal use) | Personal Account |

> **Tip**
>
> Service Users survive user offboarding and role changes; Personal Accounts break when the owner is deactivated. For any production or shared use case, always choose a Service User.

> **Info**
>
> For Service Token security (storage, rotation, revocation, encryption) and expiration strategy, see [Service Token Best Practices](https://userguide.qualytics.io/settings/access-tokens/service-token/deep-dive/best-practices/).

*Last updated: October 6, 2026.*
