Skip to main content
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.
This vault is for outbound credentials (DevHelm calling your services). For credentials authenticating into DevHelm itself, see API Keys.

​
Model

PropertyNotes
idUUID identifier for the secret.
keyStable identifier referenced from monitor configs and YAML (e.g. STRIPE_API_KEY). Conventionally uppercase with underscores. Unique within the workspace.
valueThe plaintext to store. Sent only on create and update. The API never returns it back.
valueHashSHA-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 caseHow the secret is referenced
HTTP monitor — Bearer tokenauth: { type: bearer, secret: API_TOKEN }
HTTP monitor — Basic authauth: { type: basic, secret: BASIC_CREDS } (value is username:password)
HTTP monitor — Custom headerheaders: { X-API-Key: ${API_KEY} }
Alert channel — Slack/Discord/Teams webhook URLconfig: { webhookUrl: ${SLACK_WEBHOOK_URL} }
Alert channel — PagerDuty/OpsGenie API keyconfig: { routingKey: ${PD_ROUTING_KEY} }
Webhook delivery — HMAC signing secretStored 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

  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.

​
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 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

Authenticated endpoints guide

Use secrets to monitor protected APIs.

YAML — Tags & Secrets

Define secrets in monitoring-as-code.

Environments

Variable namespaces for monitors.

secrets CLI

Manage from the command line.