How to use saved scenario secrets in a custom Action Jail action?

Custom actions from the Action Library can read API keys, tokens, and passwords from Scenario secrets (Settings). The scenario stores only a reference to the record; decryption happens on the server when the action runs.

When you need this

  • A custom action calls an external API and needs Bearer, Basic, API key, or several secrets at once.
  • The same secret is used in multiple scenarios—after Rotate secret, you do not change action code.
  • A token still lives in action code or node parameters—you want to move it to Scenario secrets.

What to know

  • The capability is enabled by the instance administrator (feature toggles under Instance settings). Without it, Credential parameters and secret references are unavailable.
  • In the secret record, Allowed consumers must include your custom action or All actions (action:*) if your instance policy allows it.
  • Add a Credential-type parameter in the action JSON config—integrators pick a record from the list in Scenario Builder without typing the secret.
  • Do not store tokens as plain strings in action code. At runtime use server-side helpers (code snippets appear under Settings → Scenario secrets after Scan legacy secrets).
  • For HTTP in custom JS, references like {{credentials.slug.field}} in request fields must be resolved explicitly before sending—unlike the Send Request node, which does this automatically.
  • OAuth2 token exchange (client credentials flow) is not a one-click setup in v1—implement it in custom action code; inline refs can supply client_id / client_secret only.

Before you start

  • An administrator enabled Scenario secrets and created the needed record (see manage scenario secrets).
  • Allowed consumers on the record includes your custom action.
  • You can edit the action in the Action Library (code and JSON config).
  • The custom action exists or you are ready to create one (see create a custom action).

Step-by-step

1. Create or update a secret for the custom action

  1. Open Settings → Scenario secrets.
  2. Click Add secret or edit an existing record.
  3. Under Allowed consumers, add your custom action from the list or leave All actions (action:*) if your instance policy allows it.
  4. Save and note the slug (e.g. crm-api-prod).

2. Add a Credential-type parameter in JSON config

  1. Open the custom action in the Action Library.
  2. In JSON configuration, add a parameter with "type": "credential":
{
  "parameters": [
    {
      "key": "crm_credential_slug",
      "type": "credential",
      "label": "CRM API secret",
      "required": true,
      "description": "Bearer token for CRM API",
      "store": "slug"
    }
  ]
}
  1. In the parameter list (UI schema), for Credential fields set:
    • Storage (slug/id) — usually slug so scenarios do not depend on internal record id;
    • Consumer field — current custom action (filled by default).
  2. Save the action.

3. Read the secret in action code

  1. In Implementation code, read parameters via this.getCurrentNodeParamsJSON().
  2. For HTTP auth (Bearer, Basic, API key in headers), use the helper that returns ready-made headers—examples appear under Scenario secrets after legacy scan or in migration hints:
async function action_my_integration() {
  const params = this.getCurrentNodeParamsJSON();
  const headers = await this.getInstanceCredentialHeaders(params.crm_credential_slug);
  // then HTTP call with headers
  return 'success';
}
module.exports = action_my_integration;
  1. For a single field (bot token, client_secret, etc.) use the single-field helper with the same slug.
  2. For SMTP or multiple fields at once use the full-payload helper only when you truly need several fields.

Copy exact helper names and snippets for your secret type from Settings → Scenario secrets → Scan legacy secrets (Custom actions tab)—slug is prefilled without revealing values.

4. Inline references in HTTP parameters (if needed)

If action parameters contain URL, headers, or body with secret reference markers (like Send Request):

  1. In Scenario Builder or action Testing, use Insert secret reference in the parameter field.
  2. In code, before sending HTTP, call the helper that resolves those markers in your request object, then send the request.

Without this step, markers stay plain text and the request will not authenticate.

5. Connect the action in a scenario

  1. In Scenario Builder add an Action node with your custom action.
  2. In CRM API secret (or your Credential parameter label), pick a record from the list.
  3. Save and test (see embed an action in a scenario).

6. Test in Action Jail

  1. Open Testing in the action editor.
  2. For Credential parameters pick a record or insert a secret field reference.
  3. Click Test Action—output is redacted; check success status and logs.

Scan and migrate inline secrets

  1. Under Scenario secrets, click Scan legacy secrets.
  2. Open Custom actions (Action Jail)—masked samples and ready code fragments replace inline tokens.
  3. Create a secret of the right type, update action code, save, and re-test.