> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets

> Store credentials securely in the DevHelm vault for use in authenticated monitor checks

The **secrets vault** stores outbound credentials your monitors and alert channels need at run time — bearer tokens, basic-auth pairs, webhook signing keys, API keys for third-party services, and similar. Secret values are encrypted at rest, exposed only to the worker that runs a check, and never returned in the clear once written.

<Tip>
  This vault is for **outbound** credentials (DevHelm calling *your* services). For credentials authenticating *into* DevHelm itself, see [API Keys](/platform/api-keys).
</Tip>

## Model

| Property        | Notes                                                                                                                                                              |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`id`**        | UUID identifier for the secret.                                                                                                                                    |
| **`key`**       | Stable identifier referenced from monitor configs and YAML (e.g. `STRIPE_API_KEY`). Conventionally uppercase with underscores. Unique within the workspace.        |
| **`value`**     | The plaintext to store. Sent only on `create` and `update`. The API never returns it back.                                                                         |
| **`valueHash`** | SHA-256 hex digest of the current value. Used by the CLI for drift detection so the YAML deploy can decide whether to push an update without seeing the cleartext. |

## What secrets are used for

| Use case                                        | How the secret is referenced                                                |
| ----------------------------------------------- | --------------------------------------------------------------------------- |
| HTTP monitor — Bearer token                     | `auth: { type: bearer, secret: API_TOKEN }`                                 |
| HTTP monitor — Basic auth                       | `auth: { type: basic, secret: BASIC_CREDS }` (value is `username:password`) |
| HTTP monitor — Custom header                    | `headers: { X-API-Key: ${API_KEY} }`                                        |
| Alert channel — Slack/Discord/Teams webhook URL | `config: { webhookUrl: ${SLACK_WEBHOOK_URL} }`                              |
| Alert channel — PagerDuty/OpsGenie API key      | `config: { routingKey: ${PD_ROUTING_KEY} }`                                 |
| Webhook delivery — HMAC signing secret          | Stored on the webhook endpoint config                                       |

References use `${KEY}` substitution at deploy time, or — in the case of HTTP monitor `auth` blocks — a typed `secret: KEY` field. Plain text is never written into the deployed monitor config.

## Managing secrets

<Tabs>
  <Tab title="Dashboard">
    1. Open **Settings → Secrets**.
    2. Click **Add Secret**, enter a key + value.
    3. Save. The dashboard list shows keys and the SHA-256 hash — never the value.
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    devhelm secrets list
    devhelm secrets create --key SLACK_WEBHOOK_URL --value "https://hooks.slack.com/..."
    devhelm secrets update SLACK_WEBHOOK_URL --value "https://hooks.slack.com/new"
    devhelm secrets delete SLACK_WEBHOOK_URL
    ```

    Full reference: [`devhelm secrets`](/cli/commands/secrets).
  </Tab>

  <Tab title="YAML">
    ```yaml theme={null}
    secrets:
      - key: API_TOKEN
        value: ${API_TOKEN}        # injected from local env at deploy time
      - key: SLACK_WEBHOOK_URL
        value: ${SLACK_WEBHOOK_URL}
    ```

    The CLI substitutes `${VAR}` from your shell environment, then pushes any value whose SHA-256 hash differs from the current vault entry. If hashes match, the secret is left untouched and is reported as `no-op` in the plan.
  </Tab>
</Tabs>

## Drift detection

The CLI never reads plaintext values back from the API. Instead, every secret has a server-computed SHA-256 `valueHash`, and `devhelm plan`/`devhelm deploy` compares it to the hash of the value about to be written:

* **Hashes match** → secret is left alone.
* **Hashes differ** → secret is updated.
* **Local definition removed but server still has it** → CLI reports the secret as orphaned (and deletes it when you pass `--prune`).

This allows config-as-code workflows to be safely re-run from CI without leaking secret values into logs or git history.

## Security model

* **Encryption at rest** with envelope encryption (AES-256-GCM data keys, KMS-managed key encryption keys).
* **Decryption only at use time** — values are decrypted just-in-time inside the worker that executes a monitor check, then discarded.
* **No read-back API.** The API only exposes `GET /api/v1/secrets` (list metadata) and `PUT`/`DELETE` on `/api/v1/secrets/{key}`. Even superadmins cannot retrieve plaintext via the API.
* **Audit logged.** Create, update, delete, and resolution-failure events are written to the org audit log.
* **Use [API key rotation](/platform/api-keys#rotation) for keys that gate access to the vault itself.**

## Lifecycle notes

* Deleting a secret that is still referenced by a monitor is allowed — the monitor will start failing at next check with a credential-resolution error. Treat secret deletion the same as any breaking config change.
* Updating a value is instant: the next check picks up the new value without redeploying the monitor.
* Secret keys are case-sensitive. `api_token` and `API_TOKEN` are different secrets.

## Next steps

<CardGroup cols={2}>
  <Card title="Authenticated endpoints guide" icon="lock" href="/guides/authenticated-endpoints">
    Use secrets to monitor protected APIs.
  </Card>

  <Card title="YAML — Tags & Secrets" icon="file-code" href="/mac/yaml/tags-and-secrets#secrets">
    Define secrets in monitoring-as-code.
  </Card>

  <Card title="Environments" icon="layers" href="/platform/environments">
    Variable namespaces for monitors.
  </Card>

  <Card title="secrets CLI" icon="terminal" href="/cli/commands/secrets">
    Manage from the command line.
  </Card>
</CardGroup>