Rotate Credentials Used by Data Apps
Rotate the credentials that Embedded and Linked Data Apps use to call Tetra, including the default app token, Service User tokens, and SQL credentials.
This procedure describes how to rotate the credentials that Data Apps (Embedded and Linked) use to call Tetra, so that those integrations keep working after you rotate the tokens described in Rotate Service User, Organization SQL, and Login User SQL JWT Tokens.
WARNINGExactly which credential a given Data App uses depends on how that app was built and configured. There is no single UI screen for "Data App credentials." Confirm with the app's owner or developer which of the mechanisms below applies before rotating, so that you don't break the app or rotate the wrong credential.
Step 0: Identify How the Data App Authenticates
| Data App type | How it typically authenticates | Action needed |
|---|---|---|
| Linked Data App (external SaaS opened through a URL tile) | Tetra doesn't issue the external application a JWT through this mechanism. If the application separately calls the Tetra API (for example, through its own API integration), it holds its own Service User or Personal token outside of Tetra's Data App configuration. | If the linked application calls the Tetra API, rotate that credential by following Rotate Service User, Organization SQL, and Login User SQL JWT Tokens, and then update it in the external application's own settings. |
| Embedded Data App: default app token | Automatically issued its own service-account JWT (the "app token") at install time, delivered through the JWT_TOKEN_PARAMETER environment variable, which points to an AWS Systems Manager Parameter Store path. Provisioned automatically per install. No Service User is involved, and there is no dedicated "regenerate" action in the Tetra admin UI for this credential. | Follow Rotate the Default App Token. |
| Embedded Data App: Service User token (only if one was configured) | Some apps additionally use a Service User JWT, created by an administrator and delivered to the app through a custom Data App Provider secret, typically because the app needs elevated permissions (for example, managed-table read/write) beyond what the default app token allows. | Follow Rotate a Service User JWT Token Used by a Data App. |
| Embedded Data App that queries Tetra Data directly through SQL/Athena | Organization-level or personal SQL credentials, the same as any other SQL client. | Follow Rotate SQL JWT Credentials Used by a Data App. |
| Embedded Data App that connects to an external system (for example, Databricks or Snowflake) through a Data App Provider | Provider-managed secrets for the external system, exposed to the app as environment variables. | Out of scope, unless the provider secret is itself a Tetra-issued JWT. In that case it's a Service User token; follow Rotate a Service User JWT Token Used by a Data App. |
Rotate the Default App Token
App tokens are provisioned per install, so uninstalling and reinstalling the Data App issues a brand-new service-account JWT for the app. This is the rotation method for this credential, because there is no separate "regenerate" action in the Tetra admin UI (the app token isn't managed through the Service Users screen).
WARNINGBack up anything in Amazon EFS storage before you uninstall. EFS is not preserved across an uninstall and reinstall — this is a common source of surprise, since EFS does survive restarts and version upgrades, just not uninstall. For example, uninstalling loses a local SQLite database and its versioned backups, and any cached generated files or images written to
/var/data. Managed tables (Databricks), Shared Settings/Secrets, and TDP Data Lake–uploaded files do survive an uninstall and reinstall — these are the safe places to move anything you can't afford to lose before rotating.
- Back up anything in EFS storage that you can't afford to lose, by moving it to a managed table, a Shared Setting/Secret, or the TDP Data Lake.
- Uninstall the Data App.
- Reinstall the app at the same version and namespace/slug.
- Confirm that the app loads and completes its normal Tetra API calls successfully with the new token.
The old token retires automatically. After the prior install is gone, its app token stops working, so no separate revoke step is needed for this credential type.
Rotate a Service User JWT Token Used by a Data App
- Sign in to Tetra with an Administrator role.
- Select Administration > Organization Settings > Service Users tab, and generate a new token for the Service User that the Data App uses. As with Agents and Connectors, TetraScience recommends a dedicated Service User per integration rather than sharing one across multiple apps or services. Copy the new token value immediately. It can't be retrieved again after the dialog closes.
- Update the token everywhere the Data App reads it from. Depending on how the app was configured, this is one of the following:
- A Data App Provider secret, which is the standard mechanism for delivering a Service User token to an embedded app. Select Administration > Data & AI Workspace > Providers, locate the provider that the app uses, and update the field that holds the token.
- An environment variable set in the Data App's own configuration in Tetra. Check the app's settings or configuration screen for an Environment Variables or Secrets section.
- A Shared Setting/Secret that the app references. Select Administration > Shared Settings, locate the secret, select Settings > Edit, enter the New Value, confirm it, and select Save.
- If the Service User's access is scoped through an Access Group, confirm that it's still included in the correct group(s) so that the app retains the data access it needs.
- Open the Data App and confirm that it loads data and completes its normal Tetra API calls successfully with the new token.
- After you confirm the app works, revoke or delete the old token (or disable the old Service User, if you created a new one) from the Service Users tab.
NOTEShared Settings and Secrets can take up to about 60 seconds to propagate after you save them. If the app fails right after the update, wait briefly and retest before assuming something is wrong.
Rotate SQL JWT Credentials Used by a Data App
If the Data App queries Tetra Data directly through SQL/Athena (rather than through the Tetra API), it uses the same organization-level or personal SQL credentials as any other SQL client. Follow the relevant section of Rotate Service User, Organization SQL, and Login User SQL JWT Tokens, and then update the connection details wherever the Data App stores them (environment variables or a Shared Setting/Secret, as described above):
General Notes
- Check with the Data App's owner or developer before rotating. For a custom-built app, the credential may be embedded in application code paths that aren't visible from the Tetra admin UI alone.
- Because a Data App can be used across a whole team, coordinate the rotation with its users so that a brief re-authentication or app reload doesn't come as a surprise.
- Provider secrets for external systems (Databricks, Snowflake, and so on) connected through a Data App Provider are a separate credential type and out of scope for this procedure, unless that provider secret is itself a Tetra-issued Service User JWT. In that case it's in scope; see Rotate a Service User JWT Token Used by a Data App.
Related Documentation
Updated about 8 hours ago