Service Token FAQ

Answers to common questions about Service Tokens and Service Users, including creation, rotation, permissions, and automation best practices.

Info

For questions about creating, deleting, and configuring Service Users (not specific to tokens), see the Service Users documentation.

General

What is a Service Token?

A Service Token is a secure credential used by a Service User to authenticate automated workflows with the Qualytics API. Unlike Personal Tokens, Service Tokens are administrator-managed and tied to dedicated user accounts designed for automation — not real people.

What is the difference between a Service Token and a Personal Token?

Service Tokens are tied to Service Users and managed by Admins. Personal Tokens are tied to individual user accounts and self-managed. For production automation, always use Service Tokens — they are independent of any human user.

Who can manage Service Tokens?

Only users with the Admin role. The Service tab in the UI is hidden from non-admin users. All API endpoints for Service Token management require the Admin role.

Can a Service User have multiple tokens?

Yes. You can create multiple tokens for the same Service User — one per environment, integration, or purpose (e.g., one for production, one for staging). This makes it easy to rotate or revoke a specific token without affecting others.

What happens to tokens if I change the Service User's role?

Existing tokens continue to work, but they immediately reflect the new role. For example, if you downgrade a Service User from Manager to Member, all its tokens can no longer trigger operations — only read data. No action is needed on the tokens themselves.

Can I migrate a Personal Token to a Service Token?

No. There is no migration path. You must create a new Service User, generate a Service Token for it, update the automation to use the new token, then revoke and delete the old Personal Token.

Creation

Can I retrieve a token after it's been generated?

No. The token value is shown only once at creation time. The platform stores a one-way hash — the original value cannot be recovered. If you lose a token, generate a new one.

What happens if I create a token with a duplicate name?

The platform returns a 409 Conflict error. Token names must be unique per Service User — the same name can exist on different Service Users, but not twice on the same one. Choose a different name or delete the existing token first.

What is a SCIM Administration Token?

A SCIM token restricts API access to SCIM provisioning endpoints only (/scim/v2/*). It is used for directory sync and automated user provisioning. The token cannot access any other API endpoint.

When should I use a SCIM-only token?

When the Service User's sole purpose is directory sync (e.g., provisioning users from Okta, Azure AD, or another identity provider). This limits the blast radius if the token is compromised.

Can I create a Service Token for a regular (Human) user?

No. The user_id parameter only accepts Service User IDs. Attempting to target a Human user returns a 400 Bad Request error.

Expiration

What happens when a Service Token expires?

The token automatically stops working. API requests using an expired token are rejected. You must generate a new token to restore automation access.

Can I restore an expired token?

The UI does not show the Restore option for expired tokens. However, expired tokens can technically be reactivated via the API by setting {"revoke": false}. Note that restoring an expired token does not extend its expiration date — the token remains expired and will not work for authentication. In practice, you should generate a new token instead.

What expiration should I use for production tokens?

365 days for production. Begin rotation at least 30 days before expiration. For staging use 180 days, for development 90 days, and for testing 7–30 days.

Can I change the expiration of an existing token?

No. Expiration is set at creation time and cannot be modified. Generate a new token with the desired expiration, update the automation, then revoke and delete the old one.

Revoking and Deleting

What happens when I revoke a Service Token?

The token is deactivated immediately — there is no grace period. Any automated system using the revoked token will lose API access instantly. A revoked token can be restored or deleted.

Can I delete an active token?

No. You must revoke the token first, then delete it. Attempting to delete an active token returns a 400 Bad Request error.

Can I restore a deleted token?

No. Deletion is permanent and irreversible. Generate a new token if you need access again.

Can I rename a token?

No. Token names are set at creation time and cannot be modified.

Token Rotation

How do I rotate a Service Token?

Generate a new token (at least 30 days before the old one expires).
Update your automation's secrets or environment variables.
Verify the automation works with the new token.
Revoke the old token.
Monitor for 7 days, then delete the old token.

How often should I rotate tokens?

At least once per year for production tokens. More frequent rotation (every 90–180 days) is recommended for sensitive environments.

Integration Scenarios

How do I integrate Service Tokens with Airflow or dbt?

Store the Service Token as a secret or environment variable in your orchestration platform (e.g., Airflow Connections, dbt environment variables). Reference it in your API calls:

import os
import requests

headers = {
    "Authorization": f"Bearer {os.environ['QUALYTICS_TOKEN']}",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://your-instance.qualytics.io/api/datastores/42/scan",
    headers=headers,
    json={"container_names": ["orders"]}
)

How do I automate token rotation in CI/CD?

Use a two-token overlap strategy: generate the new token via the API, update the secret in your CI/CD platform (e.g., GitHub Actions secrets, Vault), verify the pipeline runs successfully, then revoke the old token via API. This can be scripted as part of a scheduled maintenance job.

Can a Service Token trigger operations like Scan and Profile?

Yes — as long as the Service User has the required role and team permissions. A Manager-level Service User with team access to a datastore can trigger Sync, Profile, Scan, Export, and Materialize operations, the same as any human user with equivalent permissions.

Can I use a Service Token with the Qualytics CLI?

Yes. The Qualytics CLI accepts Service Tokens for authentication, which is the recommended approach for automated CLI workflows. See the CLI Authentication documentation.

Governance and Compliance

How do I monitor unused tokens across the organization?

Regularly review the Last Used timestamps on the Service tab. Tokens showing "Not used yet" or last used several months ago may indicate decommissioned automations. Establish a quarterly review process to revoke and delete unused tokens. See Best Practices — Monitoring and Governance.

Can I see all tokens from my team's Service Users?

Any user with the Admin role can see all Service Tokens across all Service Users on the Service tab. There is no team-level filtering — visibility is all-or-nothing at the Admin level.

How do I ensure compliance with token policies?

Establish naming conventions, enforce expiration policies (no "Never" in production), conduct quarterly access reviews, and use dedicated Service Users per integration. See Best Practices — Monitoring and Governance for a complete checklist.

Troubleshooting

My Service Token stopped working — what happened?

There are four possible reasons:

The token expired — check the expiration date on the Service Tokens tab.
The token was revoked — the status badge shows orange "Revoked".
The Service User's role was changed — if downgraded, the token may no longer have permission for the operation.
The Service User was deleted — all associated tokens are invalidated immediately.

Check the token's status badge and expiration on the Service tab to diagnose the issue.

Where do I manage Service Tokens?

Go to Settings (left sidebar) → Access Tokens → Service tab. This tab is only visible to users with the Admin role.

Security

What should I do if a Service Token is compromised?

Revoke the affected token immediately, notify your security team, review audit logs, generate a new token, update the automation, and delete the compromised token.

What if the entire Service User is compromised?

Revoke all tokens for the account immediately, create a new Service User, audit all actions performed by the compromised account, and rotate any downstream credentials or integrations.

How can I tell if a Service Token is being used?

Check the Last Used timestamp on the Service tab. It shows when the token was last used for an API request. Tokens that show "Not used yet" for an extended period may indicate the automation is no longer active.

API

Can I manage Service Tokens via API?

Yes. You can list, create, revoke, restore, and delete Service Tokens programmatically. All operations require the Admin role. See the Service Token API page for all endpoints and examples.

Can I delete an active token via API?

No. You must revoke the token first (PUT /api/user-tokens/{id} with {"revoke": true}), then delete it (DELETE /api/user-tokens/{id}). Attempting to delete an active token returns a 400 Bad Request error.