Secrets are secure credentials that are stored encrypted in Botmaker and automatically injected into your Code Actions’ HTTP requests. Use them to protect sensitive data such as API keys, access tokens, or OAuth credentials, without writing them directly into your code. When a Code Action makes a request to a URL that matches the domain configured in a Secret, Botmaker automatically adds the Secret’s data to that request.

You can:

• Create, edit, and delete Secrets.
• Define one or more base routes (domains) each Secret applies to.
• Choose how the credential is sent in the request: as a header, query parameter, form data, or JSON body.
• Let Botmaker inject the credentials transparently, without exposing them in your code.

Prerequisites

Access to your Botmaker account with the View secrets permission enabled inside the Code module. Without this permission, the Secrets button won’t appear.

At least one Code Action where you’ll use the credentials.

To create, edit, or delete Secrets you’ll also need the corresponding permissions (see the Required permissions section at the end of this article).

Key concepts

Secret: a set of encrypted credentials associated with one or more domains.

Base route: the domain or base route of the URLs the Secret applies to (for example, api.stripe.com or api.example.com/v1). A single Secret can have more than one.

Content type: defines how the credential is sent in the HTTPS request (Headers, Query Parameters, Body — Form Data, or Body — JSON). It cannot be changed once the Secret is created.

Key-value pair: each individual piece of data that makes up the credential, made of a Key field and a Value field.

Automatic injection: the process by which Botmaker detects that a request matches a Secret’s base route and adds its credentials to the request in transit.

bmSecret: the parameter you add to the rp() call in your Code Action to tell Botmaker to inject the corresponding credentials.

How to create and manage your Secrets

Step 1: Access the Secrets manager

From the Code Actions section, click the Secrets button to open the secure credentials manager. When it opens, you’ll see the list of all the Secrets created in your account, sorted from newest to oldest. For each one it shows its Description (identifying name), its Base route (the domain or route it applies to; there can be more than one), and the Last modified date.

Step 2: Create a new Secret

Click Create Secret to open the creation form and fill in the fields.

• Description (required): the name that identifies the Secret. Use a clear name that indicates which credential it represents, for example Stripe API Key or OAuth Token CRM.
• Base route (required, one or more): the domain or base route of the URLs this Secret will apply to. You can add more than one with the Add Base Route button.
• Content type (required): select how the Secret should be sent in the request (see the table below).

Keep these rules in mind for the base route:

• It must be a valid domain. Spaces and query parameters (?) are not allowed.
• It cannot overlap with another existing Secret’s base route. For example, if a Secret already exists for api.example.com, you won’t be able to create another one for api.example.com/v1, or vice versa.

Best practice: keep routes as specific as possible. If you’re going to use the same Secret for several routes that share a base, configure a single, more general base route. For example, for the endpoints https://www.base-route.com/specific1, /specific2, and /specific3: if each one uses a different Secret, configure a specific route per endpoint; if all three share the same Secret, configure a single base route https://www.base-route.com/ and it will apply to all three.

Depending on the Content type you choose, the credential is sent in a different way:

For the Headers, Query Parameters, and Form Data types, fill in the Key and Value fields for each piece of data you want to include. You can add multiple pairs with the Add button. For the Body — JSON type, enter a valid JSON object (empty values are not accepted).

Click Create secret to save. The button is only enabled when all required fields are complete and valid. To discard changes without saving, click Discard or the Back arrow.

Note: once the Secret is saved, the Content type cannot be changed.

Step 3: Edit a Secret

Click the edit icon in the row of the Secret you want to modify. You can edit the description, the base routes (add new ones or remove existing ones), and the values of the key-value pairs. Values that are already saved appear masked: you can add new pairs and overwrite existing ones, but the original pairs cannot be deleted. The Content type cannot be modified.

Step 4: Delete a Secret

Click the delete icon in the Secret’s row. A confirmation dialog will appear showing the Secret’s name and the warning that this action cannot be undone. Confirm to delete it permanently.

How automatic injection works

Secrets are not written into your code: Botmaker inserts them into the request at the moment it runs. To enable this, add the bmSecret: true parameter to the rp() call in your Code Action. That tells Botmaker to inject the corresponding credentials.

When it runs the request, Botmaker:

1. Compares the request URL against the base routes of all configured Secrets.
2. If the URL matches a Secret’s base route, it injects its credentials as a header, query param, form data, or JSON body field, according to the configured type.
3. Inserts the credentials transparently: your code doesn’t need to include them.

Example 1 — the request already sends a body

Suppose you have a Body — JSON Secret with base route https://botmaker-secrets.requestcatcher.com. If the value doesn’t exist it’s inserted; if it exists, it’s replaced.

Code in the Code Action (what you write):

function generateAccessToken() {
  return rp({
    uri: 'https://botmaker-secrets.requestcatcher.com',
    method: 'POST',
    bmSecret: true,
    body: {
      "client id": "uuID"
    },
    json: true,
  }).then(response => {
    return response.access_token;
  });
}

Final request sent to the service (after Botmaker’s injection):

{
  uri: 'https://botmaker-secrets.requestcatcher.com',
  method: 'POST',
  body: {
    "client id": "uuID",
    "client secrets": "<valor inyectado desde el Secret>"
  },
  json: true,
}

Example 2 — the request doesn’t send a body

Suppose the same Body — JSON Secret and base route https://botmaker-secrets.requestcatcher.com, but this time the rp() doesn’t send a body. Botmaker inserts the body with the credential.

Code in the Code Action (what you write):

function generateAccessToken() {
  return rp({
    uri: 'https://botmaker-secrets.requestcatcher.com',
    method: 'POST',
    bmSecret: true,
    json: true,
  }).then(response => {
    return response.access_token;
  });
}

Final request sent to the service (after Botmaker’s injection):

{
  uri: 'https://botmaker-secrets.requestcatcher.com',
  method: 'POST',
  body: {
    "hidden_body": "<valor inyectado desde el Secret>"
  },
  json: true,
}

Note: your code never sees the Secret’s value — Botmaker adds it to the request in transit according to the configured type (header, query param, form data, or JSON body field). We also don’t keep logs of the requests that use Secrets.

Common errors

Required permissions

Permissions to manage Secrets are configured inside the Code module when editing a role. With any of the three, the Secrets button becomes visible; each one enables a different capability:

A user with all three permissions has full access to the Secrets manager.

Remember to visit our Help Center for further information.