---
title: Store secure credentials for scripted browsers and API tests
source: https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/using-monitors/store-secure-credentials-scripted-browsers-api-tests
---

You can use secure credentials with synthetic monitoring to store critical information, such as passwords, API keys, usernames, etc. This prevents scripted monitor users from viewing, updating, or deleting these values unless they have explicit permissions in New Relic.

You can set secure credentials in New Relic or with the [Nerdgraph API](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/secure-credentials). The credentials are securely stored using AES-GCM 256-bit encryption at rest with keys managed by [AWS Key Management Service (KMS)](https://aws.amazon.com/kms/).

To learn how to secure sensitive information in your synthetic monitoring workflows, watch this short video (3:15 minutes):

[Video](https://www.youtube.com/embed/BLrTnqIHRrU)

## Requirements and limits [#requirements]

Before [using secure credentials](#ui-procedures), review these requirements and guidelines:

| Secure credentials  | Comments                                                                                                                                                                                                                                                                                                            |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Applicable monitors | The secure credentials feature is available for synthetic scripted browsers and API test monitors and step monitors. See [Types of synthetic monitors](https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/using-monitors/intro-synthetic-monitoring/#types-of-synthetic-monitors) for more information. |
| Permissions         | Account administrators can control which users can `create`, `view`, or `delete` secure credentials by [managing users' permissions](https://docs.newrelic.com/docs/accounts/accounts-billing/general-account-settings/factors-affecting-access-features-data).                                                     |
| Limit               | You can have a maximum of 1,000 secure credentials.                                                                                                                                                                                                                                                                 |

## Add or update secure credentials [#ui-procedures]

You can add or update secure credentials using the UI or the [synthetic monitoring Nerdgraph API](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/secure-credentials). Note, values cannot be viewed, only keys.

> #### ⚠️ CAUTION
>
> New Relic recommends not to store secure credentials/keys on the `Description` field as it can lead to potential security issues.

To add, view, edit, or delete a secure credential key for a scripted browser or API test monitor from the UI:

1.  Go to **[one.newrelic.com > Synthetic monitoring > Secure credentials](https://one.newrelic.com/synthetics-nerdlets/secure-credential-list)**.
2.  To add a new secure credential, look for the **Create secure credential +** button. If you have credentials already added, this button is at the top right.
    -   Tips for creating the **Key**: choose a username or other meaningful key name to identify the secure credential. Use alphanumeric or underscore `_` characters. Key names must be UPPERCASE.
    -   Tips for creating the **Value**: Use any combination of alphanumeric or special characters. 10000 characters maximum. This field is not accessible via [the Nerdgraph API](https://docs.newrelic.com/docs/apis/nerdgraph/examples/synthetics-api/secure-credentials).
3.  To edit an existing credential, click the ellipsis  icon for options.
4.  Associate the secure credential with a scripted browser or API test by [editing the script](#script-procedures).

After you add the secure credential to the script, the **[Secure credentials](https://one.newrelic.com/synthetics-nerdlets/secure-credential-list)** UI shows how many scripted monitors use that credential. This number is approximate and only updates after a monitor with a secure credential has actually been run.

> #### 💡 TIP
>
> You need to create secure credentials before you can create a monitor using them. This tip can come in handy when using an infrastructure-as-code tool like Terraform.

## Update the script [#script-procedures]

When using the [Synthetics UI editor](https://docs.newrelic.com/docs/synthetics/new-relic-synthetics/scripting-monitors/write-scripted-browsers) to create scripted browsers or API test monitors, follow these guidelines:

| **Script**           | **Guidelines**                                                                                                                                                                                                                                                                                                    |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Format               | Anywhere in the script where you reference the secure credential, it is accessed via the reserved New Relic `$secure` JavaScript object with dot notation. For example, `$secure.MY_SECURE_CREDENTIAL`. Properties on `$secure` are not accessible through bracket notation.                                      |
| Existing credentials | To view or select from a list of available secure credentials: - Type `$secure.` OR - Select from the dropdown in the editor UI.                                                                                                                                                                                  |
| Validation           | To validate the secure credential, follow standard procedures to [test the script](https://docs.newrelic.com/docs/synthetics/new-relic-synthetics/using-monitors/view-monitor-results) or [write an API test](https://docs.newrelic.com/docs/synthetics/new-relic-synthetics/scripting-monitors/write-api-tests). |

Any changes to the secure credential's value will automatically take effect across all monitors that use it. You do not need to also update the script.

**Exception:** If you update the script and jobs are already processing, the secure credential change will not take effect until the next time the job begins.

## Security for secure credentials [#security]

To ensure the security of your secure credentials, New Relic scrubs the secure value out of all data that goes to results in synthetic monitoring data and alerts. **New Relic employees cannot access secure credential values and must be added to the account to be able to view secure credentials**.

### Example

A secure credential is named `PASSWORD` and the value is `Pass123!`. New Relic replaces `Pass123!` with `_SECURECREDENTIAL_`

For example, a script includes:

```
$browser.get("https://example.com/" + $secure.PASSWORD)
```

The script results will show that your synthetic monitor went to `https://example.com/_SECURECREDENTIAL_`, even though it actually went to `https://example.com/Pass123!`. This ensures the value of the secure credential will not appear in the results.

### Redacted information [#redacted]

We currently redact the following from the results of your monitor:

-   The exact values of your secure credentials
-   Any percent-encoded values of your secure credentials

### Protecting your credentials in use [#protecting]

When creating a script, ensure that secure credentials are not passed to an external site or entered into a website in a way that causes them to be displayed or otherwise disclosed.

The protection mechanisms detailed above are designed to prevent disclosure of the credentials when stored by New Relic and in-text responses from the website being monitored. However, the scripting capability allows users to implement functionality that could result in the disclosure of the credentials if misused by the user. New Relic does not control the site being monitored or the actions of individual users of your organization. For this reason, you should only grant the "Use credentials" permission to users that are fully trusted and authorized to do so by your organization. To update permissions for secure credentials in Synthetics monitoring, please follow [user management concepts](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts) to control [capabilities for secure credentials](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-permissions/#synthetics).

New Relic logs instances of saving or validating monitors that include a secure credential; the logs are queryable via [NrAuditEvents](https://docs.newrelic.com/docs/accounts/accounts/account-maintenance/query-account-audit-logs-nrauditevent).

### Rotate secure credentials [#rotate-secure-credentials]

**Rotate a specific secure credential**

If credentials used in your scripts have been compromised, you can change the value in the UI to automatically update all monitor jobs:

1.  Go to **[one.newrelic.com > Synthetic monitoring > Secure credentials](https://one.newrelic.com/synthetics/secure-credential-list)**. Click on the ellipsis **...** for the credentials you want to change and click **Edit**.

    ![Screenshot of how to edit a secure credential](https://docs.newrelic.com/images/synthetic_screenshot-crop_edit-secure-credential-key.webp "Screenshot of how to edit a secure credential")

2.  Enter the new value and click **Save**.

    ![Screenshot of secure credential editing/config screen](https://docs.newrelic.com/images/synthetic_screenshot-crop_secure-credential-edit.webp "Screenshot of secure credential editing/config screen")

    The new value will be used in all monitor jobs that reference this secure credential.

**Rotate secure credentials used in a specific monitor**

If you suspect a monitor has been compromised, you should rotate all credentials used in that monitor. (If that monitor runs in a private location, you should also [rotate the private location key](https://docs.newrelic.com/docs/synthetics/synthetic-monitoring/private-locations/private-locations-overview-monitor-internal-sites-add-new-locations/#rotate-private-location-keys).)

To locate secure credentials used in a specific monitor:

1.  Go to **[one.newrelic.com > Synthetic monitoring](https://one.newrelic.com/synthetics)**.

2.  Find the monitor in the list. You can search by name, or you can enter the monitor ID into the filter text field:

    ![Screenshot of locating a specific monitor by ID](https://docs.newrelic.com/images/synthetic_screenshot-crop_locate-monitor-by-id.webp "Screenshot of locating a specific monitor by ID")

3.  Select the **Write script** tab to view the script:

    ![Screenshot showing where to find script contents in synthetic](https://docs.newrelic.com/images/synthetic_screenshot-crop_script-edit-location.webp "Screenshot showing where to find script contents in synthetic")

4.  Search for the term `$secure.` to highlight all references to secure credentials, and make a note of any you find.

    ![Screenshot showing secure credentials in use inside a script](https://docs.newrelic.com/images/synthetic_screenshot-crop_secure-credentials-in-script-example.webp "Screenshot showing secure credentials in use inside a script")

    Then, rotate any credentials you found in the script. Repeat these steps for each credential:

5.  Go to **[one.newrelic.com > Synthetic monitoring > Secure credentials](https://one.newrelic.com/synthetics/secure-credential-list)**.

6.  Copy the secret's name into the filter text field.

    ![Screenshot showing how to use the filter bar to locate a specific secure credential](https://docs.newrelic.com/images/synthetic_screenshot-crop_edit-secure-credential-by-name.webp "Screenshot showing how to use the filter bar to locate a specific secure credential")

7.  Click on the ellipsis icon **...** for the credential you want to change and click **Edit**.

    ![Screenshot of how to edit a secure credential](https://docs.newrelic.com/images/synthetic_screenshot-crop_edit-secure-credential-key.webp "Screenshot of how to edit a secure credential")