This procedure describes how to rotate the Service User JWT Tokens that Tetra Agents (File-Log, Empower, OpenLab, Chromeleon, UNICORN, LabX, HTTP Relay, and similar) and Connectors (Pluggable Connectors, Legacy Tetra Signals Connector, Legacy Tetra IDBS E-WorkBook Connector, and similar) use to authenticate to Tetra.

⚠️

WARNING

Agents and Legacy Connectors typically hold a long-lived Service User token locally (in the installed Agent's configuration, or in the Connector's own admin UI) rather than looking it up dynamically. Generating a new token for the Service User does not automatically update the Agent or Connector. You must also enter the new token into that component's own configuration, and an Agent additionally needs a restart before the change takes effect.

Who Can Perform Each Step, and What's Required After

Rotate the Service User Token for a Tetra Agent

1. Sign in to Tetra with an Administrator role.
2. Select Administration > Organization Settings > Service Users tab.
3. Locate the Service User dedicated to the Agent that you're rotating. TetraScience recommends creating a new Service User for each Agent rather than reusing one across Agents. If this Agent doesn't already have a dedicated Service User, create one now (with at least a Member role) instead of rotating a shared one.
4. Generate a new token for that Service User and copy it immediately. It can't be retrieved again after the dialog closes.
5. Make sure the Agent is stopped if it's already running.
6. On the Agent host, open the Agent's configuration (Setup/Configuration screen, or config file, depending on Agent type) and enter the new token for that Service User.
7. Restart the Agent. Changes to the Service User token don't take effect until the Agent service is restarted.
8. Confirm that the Agent reconnects successfully. Check the Agent's health and connection status in Tetra (Administration > Agents, or the relevant Agent monitoring page).
9. After the Agent is confirmed healthy on the new token, revoke or delete the old token (or disable the old Service User, if you created a new dedicated one) from the Service Users tab.

📘

NOTE

Exact configuration screen names and restart mechanics (a Windows service restart versus an in-app Reconnect action) vary by Agent type and version. Consult the specific Agent's installation guide or user manual if the steps above don't match what you see, or contact TetraScience Support.

Rotate the Service User Token for a Cloud or Hub Hosted Pluggable Connector

1. Sign in to Tetra with an Administrator role.
2. Select Data Sources > Connectors, and then select the Pluggable Connector that's hosted in the cloud or on a Tetra Hub.
3. Select Disable. This stops the Connector.
4. Select Enable. This restarts the Connector and rotates its Service User token automatically.

📘

NOTE

Disabling and re-enabling a cloud-hosted Connector or Hub through the API also rotates the Service User token.

Rotate the Service User Token for a Standalone Pluggable Connector

Rotating a Standalone Connector's token requires reinstalling the Connector.

⚠️

WARNING

Generating a new token immediately invalidates the current one, which prevents the Connector from communicating with Tetra. This functionally disables the Connector until you reinstall it with the newly generated token.

1. Sign in to Tetra with an Administrator role.
2. Select Data Sources > Connectors, and then select the Standalone Pluggable Connector.
3. Select Install. This opens the Install Connector dialog.
4. In the Install Connector dialog, select Generate Token. When prompted to confirm that you want to generate a new token and invalidate the current token for this Connector, select OK.
5. Follow the instructions in the Install Connector dialog: copy the install command, paste it on the Standalone host, and start the Connector.

📘

NOTE

If the installer prompts you for the token, copy the CONNECTOR_TOKEN value from the install command that you pasted. In some environments the -E flag isn't accepted, so the value isn't visible. As an alternative, edit the installer script in a text editor and add CONNECTOR_TOKEN=<new-value> near the beginning.

Rotate the Service User Token for a Legacy Connector

1. Sign in to Tetra with an Administrator role.
2. Select Administration > Organization Settings > Service Users tab, and generate a new token for the Service User that the Connector uses. As with Agents, use a dedicated Service User per Connector where possible, scoped to least privilege (read-only if the Connector only retrieves data; Member with read/write if it also uploads).
3. Copy the new token immediately.
4. Sign in to the Connector's own admin UI and open its TDP Configuration screen.
5. Enter the new value in the Service User Token field and select Save Settings.
6. Trigger or wait for the Connector's next Tetra query or download and confirm that it succeeds with the new token.
7. After you confirm the Connector works, revoke or delete the old token (or disable the old Service User) from the Service Users tab.

📘

NOTE

A personal user token technically works here too, but its short expiration makes it impractical for a long-running Connector. Always use a Service User token for this purpose.

General Notes

• Prefer one dedicated Service User per Agent or Connector. It limits the blast radius if a single token is compromised, and lets you rotate or revoke one integration's access without affecting others.
• If a Service User's access is scoped through an Access Group, confirm that it's still included in the correct group(s) after rotation so that the Agent or Connector retains the data access it needs.
• Rotate during a maintenance window where possible. An Agent restart interrupts data capture from the connected instrument or software until the Agent reconnects.
• If you're not sure which Service User a given Agent or Connector is currently using, check that component's configuration screen before rotating, rather than guessing and breaking the wrong integration.

Related Documentation

• Create and Edit Agents
• Manage Agents
• Create, Configure, and Update Pluggable Connectors
• Legacy Tetra Signals Connector Admin Configuration
• Legacy IDBS E-Workbook Connector - Admin Configuration
• Authentication
• Organization Settings
• Rotate Service User, Organization SQL, and Login User SQL JWT Tokens