# Service Token FAQ

Source: https://userguide.qualytics.io/settings/access-tokens/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](https://userguide.qualytics.io/settings/access/service-users/introduction/) 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. Once a token has expired, you can delete it without revoking it first.

### 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?

1. Generate a new token (at least 30 days before the old one expires).
2. Update your automation's secrets or environment variables.
3. Verify the automation works with the new token.
4. Revoke the old token.
5. 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:

```python
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/operations/run",
    headers=headers,
    json={"type": "scan", "datastore_id": 42, "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](https://userguide.qualytics.io/settings/access-tokens/service-token/api/#create-service-token), 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](https://userguide.qualytics.io/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](https://userguide.qualytics.io/settings/access-tokens/service-token/deep-dive/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](https://userguide.qualytics.io/settings/access-tokens/service-token/deep-dive/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](https://userguide.qualytics.io/settings/access-tokens/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. An expired token can be deleted directly, without the revoke call.

**Still have questions?**
Contact the Qualytics support team at
[support@qualytics.ai](mailto:support@qualytics.ai).

*Last updated: November 13, 2026.*