---
title: "Create and manage secrets | Grafana Cloud documentation"
description: "Create and manage secrets Secrets management provides a centralized location to securely store and manage values such as API keys, passwords, tokens, and credentials. Synthetic Monitoring tests reference secrets in a way that prevents them from being exposed in the UI, scripts, and logs generated by Synthetic Monitoring."
---

# Create and manage secrets

Secrets management provides a centralized location to securely store and manage values such as API keys, passwords, tokens, and credentials. Synthetic Monitoring tests reference secrets in a way that prevents them from being exposed in the UI, scripts, and logs generated by Synthetic Monitoring.

With secrets management, you can:

- Create secrets and attach metadata to secrets, such as description and labels.
- Reference secrets by name in [k6 scripted](/docs/grafana-cloud/testing/synthetic-monitoring/create-checks/checks/k6/) and [k6 browser](/docs/grafana-cloud/testing/synthetic-monitoring/create-checks/checks/k6-browser/) synthetics.
- Reset and revoke secret values.

Secrets are encrypted at rest using [envelope encryption](/docs/grafana/latest/setup-grafana/configure-security/configure-database-encryption/#envelope-encryption). Grafana Cloud stores the secrets’ metadata in one location while simultaneously encrypting and storing secret values in a different location. Secret values can only be decrypted by Synthetic Monitoring by using references to the metadata, not the encrypted value itself. This ensures that secrets are never stored permanently and are only available in memory during active use.

## Before you begin

- Users with the Grafana **Admin** role can create, edit, and delete secrets by default.
- Users with the Grafana **Editor** and **Viewer** roles can be granted access to create, edit, and delete secrets using a fixed role. Refer to the [Role-based access control](#role-based-access-control) section for more details.
- Only users with the **Admin** or **Editor** role, or the **Checks writer** permission, can use secrets when editing tests. Refer to [Manage users and teams for Synthetic Monitoring](/docs/grafana-cloud/testing/synthetic-monitoring/user-and-team-management/) for more details.
- Secrets are only supported in [k6 scripted](/docs/grafana-cloud/testing/synthetic-monitoring/create-checks/checks/k6/) and [k6 browser](/docs/grafana-cloud/testing/synthetic-monitoring/create-checks/checks/k6-browser/) synthetics.
- Only text-based secrets, such as passwords and certificates, are supported. Secrets have a limit of 24kB.
- Secret names must be 253 characters or less.
- Secret descriptions must be 253 characters or less.
- Secrets can have a maximum of 10 labels.
- Label keys must be 63 characters or less.

## Create a secret

To create a new secret:

1. Navigate to **Home** > **Testing & synthetics** > **Synthetics** > **Config**.
2. Click the [**Secrets**](/launch/a/grafana-synthetic-monitoring-app/config/secrets) tab.
3. Click **Create secret**.
4. In the **Create secret** dialog box, fill in the following fields:
   
   1. **Name**: A unique name for your secret. Use a descriptive name, such as `api-key-production`. Can contain letters, numbers, hyphens, and underscores.
   2. **Description**: An optional description explaining the secret’s purpose.
   3. **Value**: The secure value to be encrypted. This field is masked for security.
5. Click **Save** to create the secret.

## Edit a secret

To edit a secret:

1. Navigate to **Home** > **Testing & synthetics** > **Synthetics** > **Config**.
2. Click the [**Secrets**](/launch/a/grafana-synthetic-monitoring-app/config/secrets) tab.
3. Find the name of the secret you want to edit and click the **Edit** button next to it.
4. Update the fields you want to change. To update the **Value** field, click **Reset** first, and then update the secret’s value.
5. Click **Save**.

## Delete a secret

To delete a secret:

1. Navigate to **Home** > **Testing & synthetics** > **Synthetics** > **Config**
2. Click the [**Secrets**](/launch/a/grafana-synthetic-monitoring-app/config/secrets) tab.
3. Find the name of the secret you want to delete and click the trash icon next to it.
4. In the confirmation dialog box, type “Delete”.
5. Click **Delete**.

> Warning
> 
> Deleting a secret is permanent and can’t be undone. Any Synthetic Monitoring tests using a deleted secret will fail until you update them with a new secret, or a secret with the same name as the deleted secret is created.

## Use secrets in a test

To use secrets in a test:

1. Navigate to **Home** > **Testing & synthetics** > **Synthetics** > [**Checks**](/launch/a/grafana-synthetic-monitoring-app/checks).
2. Click “Add new check”.
3. Select the “Scripted” or “Browser” check type.
4. In your script:
   
   1. Import the `k6/secrets` module: `import secrets from 'k6/secrets';`
   2. Retrieve the secret value by using its name: `const secret_value = await secrets.get('test-secret-name');`
5. Use the secret value variable in your script.

Here is an example of a minimal k6 scripted test that fetches a secret value and tries to log it:

js ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```js
import secrets from 'k6/secrets';

export default async function main() {
  const secret_value = await secrets.get('test-secret-name');

  // Try logging the secret -- the value is redacted
  console.log(`try to log the secret value: ${secret_value}`);
}
```

Refer to the [k6/secrets documentation](/docs/k6/latest/javascript-api/k6-secrets/) for more details on the secrets module.

## Run k6 scripts locally with secrets

To reference secrets in a k6 script running locally, use the `mock` and `file` secret sources built into k6.

The `mock` source defines secrets as comma-separated key-value pairs after the `--secret-source=mock` command line argument. Here is an example passing the username ‘default’ and password ‘12345678’ to the script mytest.js:

sh ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```sh
k6 run --secret-source=mock=username=default,password=12345678 mytest.js
```

In mytest.js the secrets are retrieved by name:

js ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```js
import secrets from 'k6/secrets';

export default async function main() {
  const username = await secrets.get('username'); //fetches the value 'default'
  const password = await secrets.get('password'); //fetches the value '12345678'
  //...
}
```

The `file` source reads secrets from a file. This can be a better option when using many secrets or large secrets that are difficult to define on the command line. Define secrets as `key=value` pairs in a text file. Here is an example file `secrets.txt` defining the same secrets:

txt ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```txt
username=default
password=12345678
```

When running the script pass the `--secret-source=file` command line argument, followed by the filename. Here is an example passing `secrets.txt` to the script mytest.js:

sh ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```sh
k6 run --secret-source=file=secrets.txt mytest.js
```

Refer to the [k6/secrets documentation](/docs/k6/latest/using-k6/secret-source/) for more details on secret sources.

## Secret redaction

Secret values are masked in the Synthetic Monitoring output with the `***SECRET_REDACTED***` placeholder.

For example, the following script snippet:

js ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```js
const result = http.post('https://my-endpoint.test.app', '', { headers: { Authorization: `Bearer ${secret_value}` } });
```

Produces a header in the form of:

http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```http
Authorization: Bearer xm_MCp5aalOF2BGlafChR8Gu5hv
```

But that same line appears in the logs as:

http ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```http
Authorization: Bearer ***SECRET_REDACTED***
```

## Role-based access control

The ability to create, edit, and delete secrets is defined by the Grafana role assigned to a user:

- **Admins** can create, edit, and delete secrets by default.
- Only users with the **Admin** or **Editor** role, or the **Checks writer** permission, can use secrets when editing tests.

You can use Role-based access control to give users, whether they’re **Admins**, **Editors**, or **Viewers**, granular access to secrets. The following roles are available:

Expand table

| Role                  | Description                 |
|-----------------------|-----------------------------|
| Secure Values Reader  | Read and list secure values |
| Secure Values Creator | Create secure values        |
| Secure Values Updater | Update secure values        |
| Secure Values Deleter | Delete secure values        |

To assign a role to a user:

- Navigate to **Home > Administration > Users and access > Users**.
- Assign a fixed role from Fixed roles > Secret manager.

When assigning secret manager roles to users, ensure these users have been granted appropriate access to Synthetic Monitoring. For example, a user with the Grafana **Viewer** role and the **Secure Values Creator** role has the ability to create secrets, but they also need the **Checks writer** role to gain access to the Synthetic checks interface containing the secrets configuration.

Refer to [Synthetic Monitoring RBAC roles](/docs/grafana-cloud/testing/synthetic-monitoring/user-and-team-management/#synthetic-monitoring-rbac-roles) for more details about the available roles.