---
title: "How to use saved scenario secrets in a custom Action Jail action"
description: "Connect scenario secrets to a custom action via Credential-type parameters and server-side helpers—without tokens in code or scenario JSON."
---

# 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

- [x] An administrator enabled **Scenario secrets** and created the needed record (see [manage scenario secrets](/en/settings/how-to/manage-action-credentials.md)).
- [x] **Allowed consumers** on the record includes your custom action.
- [x] You can edit the action in the **Action Library** (code and JSON config).
- [x] The custom action exists or you are ready to create one (see [create a custom action](/en/actionjail/how-to/create-custom-action.md)).

## 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"`:

```json
{
  "parameters": [
    {
      "key": "crm_credential_slug",
      "type": "credential",
      "label": "CRM API secret",
      "required": true,
      "description": "Bearer token for CRM API",
      "store": "slug"
    }
  ]
}
```

3. 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).
4. 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:

```javascript
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;
```

3. For a single field (bot token, client_secret, etc.) use the single-field helper with the same slug.
4. 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](/en/actionjail/how-to/integrator-embed-actions.md)).

### 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.

## Related

- [Manage scenario secrets](/en/settings/how-to/manage-action-credentials.md)
- [What are scenario secrets](/en/settings/explanation/what-are-action-credentials.md)
- [Use secrets in Send Request](/en/scenariobuilder/how-to/use-saved-credential-in-send-request.md)
- [Create a custom action](/en/actionjail/how-to/create-custom-action.md)
- [Embed an action in a scenario](/en/actionjail/how-to/integrator-embed-actions.md)