Navigation

10.26. Store API Keys and Tokens as Tenant Secrets

Keep API keys and tokens used by workflows in encrypted, named tenant secrets: create, rotate, and delete them, and understand who can see them.

10.26. Store API Keys and Tokens as Tenant Secrets
Keep API keys and tokens used by workflows in encrypted, named tenant secrets: create, rotate, and delete them, and understand who can see them.
10. SettingsUpdated: 11/19/2026

Automations often need a credential of their own: an API key for a backup vendor, a token for a distributor's price feed, or a webhook signing key for a client's line-of-business system. When that value is pasted into a workflow step, everyone who can open the workflow can read it, and rotating it means hunting through every step that holds a copy.

Tenant secrets solve both problems. The value is stored encrypted under a name such as BACKUP_SERVICE_API_KEY. A workflow refers to the name, never the value, so the value can be rotated in one place.

Open Settings, then Secrets under Data & Integration. The page explains: "Manage secrets for use in workflows. Secrets are encrypted and can be referenced using { $secret: "SECRET_NAME" }".

Figure 1: Tenant secrets are named, encrypted values. The list shows names and activity, never values.


Who can see and change secrets

PermissionWhat it allowsDefault MSP role
secrets:viewView secret names and metadata. Values are never shown.Admin
secrets:manageCreate, update, and delete secrets.Admin

Both permissions default to the Admin role only. A user without secrets:view sees "You do not have permission to view secrets." Grant the permissions to another role only when that role owns the integrations the secrets support; see 10.17. Configure Roles, Permissions (RBAC), and API Keys for Your MSP.


Read the secrets list

The list has a Search secrets... box and these columns:

ColumnWhat it tells you
NameThe name a workflow uses to refer to the secret.
DescriptionWhat the secret is for. Use it to record the vendor and the owner.
Last UpdatedWhen the value or description last changed. A key that has not changed in a long time may be due for rotation.
Last AccessedWhen a workflow last read the value, or Never. A secret nobody has read in months is a candidate for deletion.

Create a secret

  1. Select Create Secret.
  2. Enter a Name. Names use uppercase letters, numbers, and underscores only, for example BACKUP_SERVICE_API_KEY or DISTRIBUTOR_PRICE_FEED_TOKEN. Two secrets cannot share a name.
  3. Enter the Value, the key or token itself.
  4. Add a Description that answers "What is this secret used for?", such as Datto backup API key for the nightly job-failure workflow — owned by the service manager.
  5. Select Create Secret. The page confirms Secret "BACKUP_SERVICE_API_KEY" created.

The value cannot be viewed again after it is saved. Keep the vendor's own record of the key, or issue a new one when you need to rotate.


Rotate a secret

When a vendor key is reissued, or when someone who knew the value leaves:

  1. Select Edit secret on the row.
  2. Enter the new value in Value. Leaving the field empty keeps the current value, so you can update only the description.
  3. Select Update Secret.

Every workflow that refers to the name picks up the new value on its next run. Check the next run of each workflow that uses the secret to confirm the new key works.


Delete a secret

  1. Select Delete secret on the row.
  2. Read the warning. When workflows use the secret, the dialog shows "This secret is used by N workflow(s)" and "Deleting it will cause those workflows to fail when they try to access this secret."
  3. Type the secret's name to confirm, then select Delete Secret. Deletion cannot be undone.

Update or retire the workflows that use a secret before deleting it.


How workflows use a secret

A workflow refers to a secret with { $secret: "SECRET_NAME" } in place of a literal value. The value is read from the encrypted store when the step runs.

The visual workflow designer does not offer a secret picker. A step field that already holds a secret reference is shown as Legacy mapping no longer supported here, with the choice to replace it with a reference to workflow data or a fixed value. Secret references therefore come from workflow definitions that already contain them. For credentials that an integration needs, use that integration's own settings screen, which stores its keys separately. For more on workflow governance, see 15.7. Workflow Security and Governance.


When the page is read-only

On some self-hosted deployments, the secret store cannot accept writes. The page then shows a banner, "Secret storage is read-only in this environment." or "Secret storage is not configured for durable writes in this environment.", and disables Create Secret, Edit secret, and Delete secret. Existing secrets stay readable by workflows. Ask whoever administers the installation to configure durable secret storage before adding new secrets.


Audit trail

Creating, updating, and deleting a secret writes an audit record. Together with Last Accessed, this lets you confirm who changed a key and whether anything still uses it.