Skip to content

Service Token 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 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.

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

Token Storage

  • Use secure secrets managers (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault).
  • Load tokens through environment variables in deployment configurations.
  • Encrypt tokens at rest.
  • Rotate tokens on a defined schedule.
  • Use SCIM-only tokens when the Service User is used exclusively for directory sync.
  • Commit tokens to Git or any version control system.
  • Store tokens in plain or unencrypted text files.
  • Share tokens through email, chat, or other unsecure channels.
  • 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.

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 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 rotated regularly, especially before they expire.

Rotation Process

  1. Create 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 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 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) Manager Requires access to read datastores, containers, and quality checks.
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 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
Ad-hoc API exploration Personal Token
Qualytics CLI (personal use) Personal Token

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.