Documentation Grafana Cloud Security and account management Manage secrets

Manage secrets

Secrets management provides a centralized UI for storing and managing sensitive information such as passwords, API keys, tokens, and other credentials used across your Grafana instance. Instead of embedding credentials directly into k6 tests or Synthetic Monitoring checks, you can store them as encrypted secrets and reference them by name.

Before you begin

To access secrets management, you need:

• A Grafana Cloud stack.
• Either the Admin role or appropriate role-based access control (RBAC) permissions. For the permissions required for secrets management, refer to Permissions below. For general RBAC configuration, refer to Role-based access control.

Key concepts

This section describes the core concepts you need to understand before working with secrets management.

Secure values

A secure value is an encrypted secret that you can reference from supported Grafana services and integrations. Each secure value has:

• A unique name
• A short description
• An encrypted value
• Optional metadata such as labels and decrypters.

After you store a secure value, Grafana never displays the secret value again. You can update or delete the secure value but you can’t retrieve the original plaintext secret.

Keepers

A keeper is the backend that stores encrypted secret values. Grafana uses the built-in system keeper, which stores secrets encrypted in the Grafana database, by default.

Secrets are encrypted at rest using 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 decrypters 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.

The keeper associated with each secure value appears in the secrets list.

Decrypters

Decrypters control which Grafana services can read a secret’s value. When you create or edit a secure value, you can select one or more decrypters from the list of supported services. If you do not select any decrypters, the secure value is stored but no service can read it.

The following decrypters are available:

Labels

Labels are optional key-value pairs that help you organize your secrets. For example, you might use labels like environment: production or team: platform.

Label names and values must follow these rules:

• Start and end with a letter or number.
• Contain only letters, numbers, dashes (-), underscores (_), and periods (.).
• Be no longer than 63 characters.

You can add up to 10 labels per secure value.

Access secrets management

To access the secrets management page, follow these steps:

1. Sign in to Grafana.
2. Go to Administration > Secrets Management.

The secrets management page displays a list of all secure values in your Grafana instance. You can search for secure values by name using the filter bar at the top of the page.

Create a secret

To create a new secret, follow these steps:

1. Go to Administration > Secrets Management.

2. Click Create secure value.

3. In the Create secret dialog box, complete the following fields:

   Expand table

   Field	Required	Description
   Name	Yes	A unique name to identify the secret. Use lowercase letters, numbers, dashes, and periods. The name must start and end with a letter or number. Maximum 253 characters.
   Description	Yes	A short description of the purpose of this secret. Maximum 253 characters.
   Value	Yes	The secret value to store. This value is encrypted and never displayed after creation. Maximum 24 KiB.
   Decrypters	No	The Grafana services authorized to decrypt this secret. For example, Synthetic Monitoring or k6 Cloud.
   Labels	No	Key-value pairs to categorize the secret. You can add up to 10 labels.

4. Click Create.

A success notification confirms that the secret was created. The new secure value appears in the secrets list.

Naming conventions

Secret names must follow these rules:

• Start and end with a letter or number.
• Contain only lowercase letters, numbers, dashes (-), and periods (.).
• Be unique within the Grafana instance.
• Be no longer than 253 characters.

Choose descriptive names that indicate the secret’s purpose. For example, prod-db-password or monitoring-api-key.

Edit a secret

You can update a secret’s description, value, decrypters, and labels. You can’t change the name of an existing secret.

To edit a secret, follow these steps:

1. Go to Administration > Secrets Management.
2. Find the secret you want to edit and click the Edit button next to it.
3. In the Edit secret dialog box, update the fields you want to change. To update the Value field, click Reset first, then update the secret’s value.
4. Click Update.

Delete a secret

Deleting a secret is irreversible and breaks any references to the secret across your Grafana instance.

To delete a secret, follow these steps:

1. Go to Administration > Secrets Management.
2. Find the secret you want to delete.
3. Click the delete icon on the secret item.
4. In the confirmation dialog box, enter delete to confirm.
5. Click Delete.

API access

You can manage secrets programmatically using the Secrets Management API. The API provides endpoints for creating, reading, updating, and deleting both keepers and secure values.

The base path for all secrets management API endpoints is:

Copy

/apis/secret.grafana.app/v1beta1

For more information, refer to Secrets Management API.

Permissions

The following table describes the RBAC permissions for secrets management and what each allows:

Permissions are managed through Grafana’s role-based access control (RBAC). For more information, refer to Role-based access control.