Secrets store sensitive values such as API keys, access tokens, passwords and connection strings, so that your scripts and integrations can use them without those values ever appearing in code.

Secrets have their own page under Workspace Administration, where you can see every secret in your workspace, create and update them, check where each one is used, reveal a value when you need it, and delete secrets you no longer want.

Where to find Secrets

In the left sidebar, open Workspace Administration and select Secrets, directly below Script Engine. The breadcrumb reads Workspace Administration / Secrets.

If you have managed secrets before, you will have used the Workspace Secrets tab inside Script Engine. That tab has been removed. Script Engine now goes straight from its header into your scripts, and everything to do with secrets lives on this page.

The Secrets list

The page lists every secret in your workspace in three columns:

Name the name you gave the secret. The column is sortable, and sorted A to Z by default.
Used in how many places reference the secret, for example 3 places. Click the value to see exactly where. A secret that is not referenced anywhere shows --.
Value a masked preview that shows only the last four characters. The full value is never displayed in the list.

Use the search field at the top of the page to filter the list by name.

If your workspace has no secrets yet, the page shows No secrets yet. along with a New Secret button so you can create the first one.

Create a secret

Click New Secret.
Enter a Secret Name. Names must be unique within the workspace.
Enter the Value, which is the API key, token or password itself.
Click Create Secret.

Both fields are required, so Create Secret stays disabled until each one contains a value. The value is encrypted when you save it, and it is never shown again anywhere in the product except through the Reveal action.

Name secrets the way you would name an environment variable, in uppercase with underscores, such as STRIPE_API_KEY or WEATHER_API_KEY. That is how script authors will refer to them.

Edit a secret

Choose Edit on the secret's row. From the Edit Secret modal you can:

Rename the secret. The name is a label, so renaming it will not break scripts or integrations that already use it.
Replace the value. Secret values are write only, so the current value is shown masked and can never be read back from this modal. Leave the field as it is to keep the existing value, or type a new value to overwrite it.

The new value is encrypted on save and takes effect everywhere the secret is used. That means you can rotate a credential once, here, and every script and integration that references the secret picks up the new value. There is no need to update them one by one.

Reveal a value

Revealing a secret takes two steps, because the action is recorded.

Choose Reveal on the secret's row. A Reveal This Secret? warning appears, confirming that viewing the value is recorded, that your name and the time are saved, and that Administrators can see who revealed each secret.
Click Reveal Secret. The full value is displayed in a read only field with a Copy button, so you can copy it without selecting the text.

Click Close when you are done. Reveal is the only place in SmartSuite where a secret value is shown in full, and each reveal is recorded with the member's name and the time.

See where a secret is used

Click the Used in value on any row to open a modal titled {Secret name} is used in:. It lists every dependent by name, along with its type, either Script or Integration.

It is worth checking this list before you rotate or delete a secret, so you know what will be affected.

Delete a secret

Choose Delete on the secret's row. If the secret is in use, an Are You Sure? confirmation warns you that the secret is used in a number of instances and that deleting it will turn them off. The affected scripts and integrations are listed by name and type, along with a reminder that the action cannot be undone.

Confirm with Yes, Delete Secret and SmartSuite turns off each dependent script and integration first, then removes the secret. If a dependent cannot be turned off, the deletion stops, so nothing is ever left running against a secret that no longer exists.

If you are replacing a credential rather than retiring it, edit the secret and replace its value instead. Dependents keep running and pick up the new value automatically.

Using secrets in scripts

Scripts reference workspace secrets, they never store the values. In the script definition you map an environment variable name to the secret you want to use:

{
  "secrets": {
    "WEATHER_API_KEY": "<secret>"
  }
}

At run time SmartSuite injects the value under the name you declared, and your handler reads it from context.secrets:

exports.handler = async (payload, context) => {
  const apiKey = context.secrets.WEATHER_API_KEY;

  if (!apiKey) {
    throw new Error("Missing required secret: WEATHER_API_KEY");
  }

  // use apiKey to call the external service
};

A few things to know:

A script stores only a reference to the secret. The value is injected at run time and is never saved with the script.
A script can only see the secrets it references. It has no access to other scripts' secrets or to other workspaces.
If a script references a secret that does not exist, saving the script fails rather than deploying a script that cannot run.
Deleting a secret turns off the scripts and integrations that reference it, as described above.
Scripts no longer carry their own secret values. If you previously passed raw values in a script's secrets object, create those values as workspace secrets and reference them by name instead.

Good practice

Never hardcode credentials in a script. Always read them from secrets.
Check Used in before you rotate or delete a secret.
Rotate a credential by replacing the secret's value rather than deleting and recreating it.
Never log a secret value or return it from a script.
Keep separate secrets for test and production credentials.
Reveal a value only when you actually need it, since every reveal is recorded.

Secrets Management