---
title: "Manage secrets | Grafana Cloud documentation"
description: "Store and reference sensitive values, such as API tokens, in Grafana Workflows using the Workflows Secrets page or Grafana Secrets Management."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Manage secrets

> Note
> 
> Grafana Workflows 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 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](/docs/grafana-cloud/platform/workflows/manage-access/#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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```yaml
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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

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

For details on how to find and fix this error, refer to [Troubleshoot workflows](/docs/grafana-cloud/platform/workflows/troubleshoot/#my-secret-returned-401-or-secret-not-found).

## Use Grafana Secrets Management

Secrets created in [Grafana Secrets Management](/docs/grafana-cloud/security-and-account-management/manage-secrets/) 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](/docs/grafana-cloud/platform/workflows/create-workflows)
- [Load incident data](/docs/grafana-cloud/platform/workflows/load-incident-data)
- [Load alert group data](/docs/grafana-cloud/platform/workflows/load-alert-group-data)
- [Use CEL expressions](/docs/grafana-cloud/platform/workflows/use-expressions)
- [Troubleshoot workflows](/docs/grafana-cloud/platform/workflows/troubleshoot)
- [Step and trigger types reference](/docs/grafana-cloud/platform/workflows/reference)