# Service Token Best Practices

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

Follow these guidelines to keep your Service Tokens secure, well-organized, and production-ready.

## Service User Naming Conventions

When creating a Service User for your automation tokens, choose a descriptive name — it appears in audit logs and helps trace actions back to the specific integration. The system automatically generates an ID from the name you provide.

> **Info**
>
> For details on creating and configuring Service Users, see the [Service Users](https://userguide.qualytics.io/settings/access/service-users/introduction/) page.

**Example:**

- **Original Name:** "Pipeline Automation"
- **Auto-Generated ID:** `pipeline_automation@service`

The system applies the following sanitization rules: lowercase letters, spaces converted to underscores, special characters removed.

- Yes `pipeline_automation@service` — Clear and specific purpose.
- Yes `alation_sync@service` — Reflects the integration name.
- Yes `finance_metrics@service` — Indicates the business domain.
- No `service1@service` — Not descriptive enough.
- No `temp@service` — Unclear and vague.
- No `test123@service` — Too generic.

## Token Storage

- Yes Use secure secrets managers (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault).
- Yes Load tokens through environment variables in deployment configurations.
- Yes Encrypt tokens at rest.
- Yes Rotate tokens on a defined schedule.
- Yes Use SCIM-only tokens when the Service User is used exclusively for directory sync.
- No Commit tokens to Git or any version control system.
- No Store tokens in plain or unencrypted text files.
- No Share tokens through email, chat, or other unsecure channels.
- No Reuse the same token across multiple environments.

## Token Expiration Strategy

Set expiration periods based on environment type:

| Environment | Recommended Expiration | Notes |
| --- | --- | --- |
| **Production** | 365 days | Begin rotation at least 30 days before expiration. |
| **Staging** | 180 days | Shorter duration due to non-production usage. |
| **Development** | 90 days | Frequent rotation aligns with active development cycles. |
| **Testing** | 7–30 days | Ideal for temporary testing or short-lived workflows. |

> **Note: API flexibility**
>
> The UI restricts expiration to 30/60/90/1 Year/Never. Via the API, you can set any value from 1 to 365 days for fine-grained control (e.g., 180 days). See the [Service Token API](https://userguide.qualytics.io/settings/access-tokens/service-token/api/) for details.

> **Warning**
>
> Avoid using the **Never** expiration option for production tokens. Implement periodic token rotation to minimize security risks.

## Token Rotation

For security best practices, tokens should be changed regularly, especially before they expire.

### Rotation Process

1. **[Create](https://userguide.qualytics.io/settings/access-tokens/service-token/managing/generate-service-token/)** a new token (at least 30 days before expiration). Give it a clear name (e.g., `production-integration-2026`).
2. **Share the new token** with your integration or engineering team.
3. **Update secrets** in your environment variables or secrets manager with the new token.
4. **Verify** that your integration or automation works correctly using the new token.
5. **Monitor token usage** — check the Last Used timestamp to ensure the new token is active and the old token is no longer in use.
6. **[Revoke](https://userguide.qualytics.io/settings/access-tokens/service-token/managing/revoke-service-token/)** the old token once you've confirmed the new token works.
7. **Observe a grace period** — monitor for at least 7 days to ensure no unexpected usage occurs on the old token.
8. **[Delete](https://userguide.qualytics.io/settings/access-tokens/service-token/managing/delete-service-token/)** the old token after the grace period.

## Role Assignment

Assigning the correct role to a Service User enforces the principle of least privilege.

| Use Case | Recommended Role | Rationale |
| --- | --- | --- |
| **Data catalog sync** (Alation, Atlan) | Member or Manager | Starting a sync limited to selected datastores needs the **Editor** team permission on each of them, which a **Member** can have. Starting a full sync needs the **Manager** role, and it still skips any datastore where the user lacks **Editor**, so grant **Editor** on every datastore the sync should cover (an **Admin** covers all of them). Reading datastores, containers, and quality checks alone needs only the **Reporter** team permission. |
| **Data pipeline automation** | Manager | Needs permission to trigger operations and create containers. |
| **Qualytics CLI automation** | Manager | Must be able to run profiling and scanning operations. |
| **Read-only API access** | Member | Only needs to view metrics, anomalies, and quality results. |
| **BI tool integration** | Member | Only requires read access to data quality outputs. |
| **Full platform automation** | Admin | Requires full control over users, teams, integrations, and platform resources. |

> **Tip**
>
> Start with the **Member** role whenever possible, and escalate only if the integration requires additional capabilities. For the full role permissions matrix, see the [Permissions](https://userguide.qualytics.io/settings/access-tokens/service-token/deep-dive/permissions/) page.

## When to Use Service Tokens vs Personal Tokens

| Scenario | Use |
| --- | --- |
| Production pipelines and automation | Service Token |
| Data catalog integrations | Service Token |
| Shared automation across teams | Service Token |
| CI/CD pipelines (long-lived) | Service Token |
| Personal development and testing | [Personal Token](https://userguide.qualytics.io/settings/access-tokens/personal-token/introduction/) |
| Ad-hoc API exploration | [Personal Token](https://userguide.qualytics.io/settings/access-tokens/personal-token/introduction/) |
| Qualytics CLI (personal use) | [Personal Token](https://userguide.qualytics.io/settings/access-tokens/personal-token/introduction/) |

> **Tip**
>
> Service Tokens are tied to Service Users, not to real users. If the admin who set up the automation leaves the organization, the tokens continue to work. Personal Tokens break when the user's account is deactivated.

## Monitoring and Governance

Regularly monitor token activity and conduct periodic reviews to maintain operational security.

**Monthly:**

- Check **Last Used** timestamps — revoke tokens unused for 90+ days.
- Review each Service User's role to ensure it remains appropriate.
- Watch for unexpected token usage or failed authentication attempts.

**Quarterly:**

- [ ] Each Service User has a clearly documented purpose.
- [ ] Token names accurately reflect their usage.
- [ ] No tokens are close to expiration without a rotation plan.
- [ ] Roles follow the principle of least privilege.
- [ ] No orphaned tokens exist (tokens tied to deleted Service Users).

**Compliance:**

- Use dedicated Service Users for production integrations — Personal Tokens should only be used in development.
- Require admin approval before creating Service Users.
- Document ownership and purpose for each account.

## Incident Response

### If a Token Is Compromised

1. **Immediate Actions** — Revoke the affected token, notify your security team, and review audit logs.
2. **Investigation** — Analyze all API requests made using the token. Determine scope of unauthorized access and check if data was altered or exfiltrated.
3. **Remediation** — Generate a new token, update integrations, delete the compromised token, and document the incident.
4. **Prevention** — Strengthen storage and handling practices, improve monitoring and alerts, and provide security training if needed.

### If a Service User Is Compromised

1. Immediately revoke **all tokens** for the account.
2. Create a new Service User.
3. Audit all actions performed by the compromised account.
4. Rotate any downstream credentials, keys, or integrations.

*Last updated: October 6, 2026.*