Skip to main content

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.

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
keyStable identifier referenced from monitor configs and YAML (e.g. STRIPE_API_KEY). Conventionally uppercase with underscores.
valueThe plaintext to store. Sent only on create and update. The API never returns it back; reads expose null.
environmentOptional environment slug. When set, this scoped value overrides the global value of the same key when the monitor’s environment matches.
hashSHA-256 fingerprint 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, and (optionally) pick an environment.
  3. Save. The dashboard list shows keys, environment scope, and the SHA-256 hash — never the value.

​
Environment-scoped secrets

A secret can exist at the global scope and/or scoped to one or more environments. When a monitor references a secret at deploy time, resolution is:
  1. Look for a value scoped to the monitor’s environment slug.
  2. Fall back to the global value.
  3. If neither exists, the deploy fails with a secret_not_found error.
This lets you keep a single STRIPE_API_KEY reference in your monitor config and serve sk_test_... to staging while production gets sk_live_.... 
secrets:
  - key: STRIPE_API_KEY
    value: ${STRIPE_TEST_KEY}
    environment: staging
  - key: STRIPE_API_KEY
    value: ${STRIPE_LIVE_KEY}
    environment: production

​
Drift detection

The CLI never reads plaintext values back from the API. Instead, every secret has a server-computed SHA-256 hash, 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 on --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 API. GET /api/v1/secrets/{key} returns the metadata (hash, scope, timestamps) but never the value. 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

Scope secrets per deployment stage.

secrets CLI

Manage from the command line.