Skip to main content

Service Tokens (Profiler & CLI)

Service tokens enable authenticated access for the Zymtrace CLI, Profiling Agent, MCP, as well as programmatic API access to Zymtrace.

When authentication is enabled (local or oidc) along with service token authentication, both the Zymtrace profiler and Zymtrace CLI can be authenticated using a service token.

Prerequisites

Ensure that auth.serviceToken.enabled is set to true in your Helm values. This enables the service token functionality required for Zymtrace profiler and Zymtrace CLI authentication. See the overview page for configuration details.

Getting a Service Token​

  1. Log in to Zymtrace as an admin or user with service:token:create permission

  2. Navigate to Your profile picture → Account → Service Tokens Service Token list

  3. Click Create Token

Create service token dialogue

  1. Provide a descriptive name for the token (e.g., "Production Profiler - Server01" or "CI/CD CLI Access"), select when the token should expire and click 'Create Token'

  2. Copy the token and store it securely (it won't be shown again)

  3. Save the token in a secure location

Using Tokens with Zymtrace Profiler​

Pass the token to the profiler using the -auth-token flag:

# Using CLI flag
sudo ./zymtrace-profiler \
  -collection-agent=your-gateway-host.com:443 \
  -auth-token="your-service-token-here"

You can also set the token via the ZYMTRACE_AUTH_TOKEN environment variable:

export ZYMTRACE_AUTH_TOKEN="your-service-token-here"
sudo ./zymtrace-profiler \
  -collection-agent=your-gateway-host.com:443

Helm (Kubernetes)​

For Helm deployments, source the token from a Kubernetes Secret with profiler.authToken instead of passing it as a CLI arg. The chart exposes it to the agent as ZYMTRACE_AUTH_TOKEN, keeping it out of the rendered pod spec.

Let the chart create the Secret from a plain value:

helm install profiler zymtrace/profiler \
  --namespace zymtrace \
  --set profiler.authToken.value="your-service-token-here"

Or reference an existing Secret you manage (takes precedence over .value; key defaults to auth-token):

kubectl create secret generic my-zymtrace-token \
  --namespace zymtrace \
  --from-literal=auth-token="your-service-token-here"

helm install profiler zymtrace/profiler \
  --namespace zymtrace \
  --set profiler.authToken.existingSecret.name=my-zymtrace-token \
  --set profiler.authToken.existingSecret.key=auth-token

See the profiler install guide for details.

Token Security
  • Never commit service tokens to version control
  • Rotate tokens periodically
  • Use separate tokens for different environments (dev, staging, production)
  • Revoke tokens if they are compromised

For AI assistant integration via MCP, see the MCP documentation page.

Token Management​

Viewing Tokens​

View all service tokens in Zymtrace settings page:

  1. Navigate to Your profile picture → Account → Service Tokens
  2. See token name, type, creation date, and expiration

Revoking Tokens​

To revoke a service token:

  1. Navigate to Your profile picture → Account → Service Tokens
  2. Find the token you want to revoke
  3. Click the three dots menu
  4. Select Revoke
  5. Confirm the revocation
Immediate Effect

Revoking a token takes effect immediately. Any Zymtrace profiler instances or CLI tools using the token will lose access.