---
title: "Create and manage secrets | Grafana Cloud documentation"
description: "Create and manage secrets Note Secrets management is currently in public preview. Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available."
---

# Create and manage secrets

> Note
> 
> Secrets management is currently in [public preview](/docs/release-life-cycle/). Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.

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

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/k6/author-run/script-editor/) and [k6 browser](/docs/grafana-cloud/testing/k6/get-started/run-your-first-browser-tests/) tests in Grafana Cloud, and also tests executed by running `k6 cloud` locally.
- 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 k6 tests by referencing the secret name, 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

- You need to have the proper clearance to manage secrets, refer to the [Role-based access control](#role-based-access-control) section for more details.
- 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 **Testing & synthetics** > **Performance** > [**Settings**](/launch/a/k6-app/settings/).
2. Click the **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.
   4. **Labels**: Extra metadata to help with organizing secrets.
5. Click **Save** to create the secret.

Note that the secret is available for use only in Grafana Cloud k6 tests. You can’t access it with other Grafana Cloud applications.

## Edit a secret

To edit a secret:

1. Navigate to **Testing & synthetics** > **Performance** > [**Settings**](/launch/a/k6-app/settings/).
2. Click the **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 **Testing & synthetics** > **Performance** > [**Settings**](/launch/a/k6-app/settings/).
2. Click the **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 k6 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 **Testing & synthetics** > **Performance** > **Projects**.
2. Create a new project or select a previously created one.
3. Click “Create new test”.
4. Click “Start scripting”.
5. 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');`
6. 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.

> Note
> 
> The secrets module is available in k6 version `1.5.0` or later. If you’re [overriding the k6 version](/docs/grafana-cloud/testing/k6/author-run/k6-versions/#override-k6-versions-and-extension-versions), ensure the version is `1.5.0` or later. Secrets aren’t available when you run tests in [Private Load Zones](/docs/grafana-cloud/testing/k6/author-run/private-load-zone/).

## Run k6 scripts locally with secrets

There are different ways to reference secrets in a k6 script running locally, as there are several secret sources built into k6.

In some of these secret sources, the user must provide the secret values. That is the case for the `mock` source (secrets are defined as comma-separated key-value pairs after the `--secret-source=mock` command line argument), the `file` source (secrets are read from a file), or the `url` source (secrets are fetched from any HTTP service). Refer to the [Secret source](/docs/k6/latest/using-k6/secret-source/) documentation for more details on those.

If the secrets are stored in Grafana Cloud, they can be retrieved when running k6 from the command line by using the `k6 cloud` command. Note that the k6 version must be equal to or greater than `1.5.0`.

Secrets can’t be currently retrieved when running a test by using `k6 cloud --local-execution`.

## Role-based access control

- Only users with the **Admin** or **Editor** role, or the **Performance Testing (k6): Editor** permission, can use secrets when editing tests. Refer to [Manage projects and users](/docs/grafana-cloud/testing/k6/projects-and-users/) for more details.

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

**Admins** and **Editors** can create, edit, and delete secrets by default. On the other hand users with the Grafana **Viewer** role can be granted access to create, edit, and delete secrets using specific roles.

You can use those 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 **Administration** > **Users and access** > **Users**.
- Click in the **Role** column for the desired user, and scroll to **Plugin Roles** > **Performance Testing (k6)**.
- Assign the desired roles.