Documentation Grafana Cloud Platform Workflows Manage secrets

Manage secrets

Secrets let you reference sensitive values, such as API tokens, without including them in workflow definitions. The Workflows app has its own Secrets page, which is the recommended way to manage secrets. You can also reference secrets created in Grafana Secrets Management, as long as they allow the grafana-workflows decrypter.

Before you begin

To create or use secrets in workflows, you need:

• Access to the Workflows app in your Grafana Cloud stack
• Permission to work with secrets. To see secrets on the Secrets page, you need secret.securevalues:read. To create, edit, or delete them, you also need secret.securevalues:create, secret.securevalues:write, or secret.securevalues:delete. For details, refer to Manage access to secrets.

Create a secret in the Workflows app

Secrets that you create on the Workflows Secrets page work with Workflows automatically, so you don’t need any extra configuration.

To create a secret:

1. In Grafana Cloud, open the Workflows app.
2. On the home page, click Manage secrets.
3. Click Create secret.
4. Enter a Name. The name becomes part of the URI you reference in the workflow.
5. Enter a Description.
6. Enter the Value.
7. Optionally, click Add label to add labels.
8. Click Create.

The secret is available to any workflow in the same stack.

Reference a secret in a workflow

Declare secret references in the resources.secrets section of the workflow definition. Each entry maps a reference name to a secret URI in the form secret://<SECRET_NAME>.

YAML Copy

spec:
  resources:
    secrets:
      api_token: "secret://my-api-token"
  steps:
    - id: call-api
      type: http.call
      inputs:
        method: "GET"
        url: "https://api.example.com/data"
        authMethod: "bearer"
        authSecret: "${resources.secret.api_token}"

In this example:

• my-api-token is the secret name as it appears on the Secrets page.
• api_token is the reference name you use inside the workflow.
• When the step runs, Workflows replaces ${resources.secret.api_token} with the secret’s value.

Use secret references in step inputs

To use a secret in a step, write ${resources.secret.<KEY>}, where KEY is the reference name from resources.secrets.

Reference names use letters, digits, and underscores, for example, api_token. Don’t use hyphens. A reference such as ${resources.secret.api-token} causes a validation error when you save the workflow.

You can use secrets only in the authentication fields of an http.call step: authSecret, authUsername, and authPassword. A secret reference in any other field causes a validation error when you save the workflow.

Edit or delete a secret

To update or remove a secret:

1. In the Workflows app, on the home page, click Manage secrets.
2. Find the secret in the list.
3. Click Edit to change the value, description, or labels, or click Delete to delete the secret.

If you delete a secret that a workflow still uses, the next run of that workflow fails before any steps run, with the following message:

Copy

secret verification failed: secret "<KEY>" (secret://<NAME>): <REASON>

For details on how to find and fix this error, refer to Troubleshoot workflows.

Use Grafana Secrets Management

Secrets created in Grafana Secrets Management can also be referenced from a workflow. Use this path when you need to share a secret with multiple Grafana apps.

To create a secret in Grafana Secrets Management for use with Workflows:

1. Create the secret in the Grafana Cloud UI or through the Grafana Secrets Management API.
2. Add the grafana-workflows decrypter so Workflows can read the secret when a workflow runs.
3. Note the secret name.

To reference the secret, use secret:// followed by the secret’s exact name, for example, secret://my-api-token. Don’t include a path in the URI.

Understand secret scope

Secrets are scoped to your Grafana Cloud stack. A secret created in stack A isn’t visible to a workflow running in stack B. Workflows reads secret values when a step runs, and secret fields show [REDACTED] in run details.

Next steps

• Create workflows
• Load incident data
• Load alert group data
• Use CEL expressions
• Troubleshoot workflows
• Step and trigger types reference