Monitoring Authenticated Endpoints

By the end of this guide, you’ll have an HTTP monitor securely checking an endpoint that requires authentication, with credentials stored in the DevHelm vault.

Prerequisites

DevHelm CLI installed or an API token
An API endpoint that requires authentication
Credentials for that endpoint (API key, bearer token, or basic auth)

Supported auth types

DevHelm supports four authentication methods for HTTP monitors:

Type	Description	Header format
`bearer`	Bearer token	`Authorization: Bearer <token>`
`basic`	Username + password	`Authorization: Basic <base64>`
`api_key`	API key in a query parameter or header	Configurable
`header`	Custom header with a static value	Any header name

Store credentials in the vault

Never put credentials directly in your config files. Store them in the DevHelm vault:

devhelm secrets create --key API_BEARER_TOKEN --value your-secret-token

For YAML-based config, reference vault secrets by name from the secrets: section. For monitors created via the CLI or API, attach auth afterwards with the monitor auth API, referencing the vault secret’s UUID.

Create an authenticated monitor

Bearer token

secrets:
  - key: API_BEARER_TOKEN
    value: ${API_BEARER_TOKEN}

monitors:
  - name: Private API Health
    type: HTTP
    config:
      url: https://api.example.com/private/health
      method: GET
    auth:
      type: bearer
      secret: API_BEARER_TOKEN
    frequencySeconds: 60
    regions:
      - us-east

# 1. Create the monitor
devhelm monitors create \
  --name "Private API Health" \
  --type HTTP \
  --url https://api.example.com/private/health \
  --frequency 60 \
  --regions us-east

# 2. Attach auth via the monitor auth API
curl -X PUT https://api.devhelm.io/api/v1/monitors/<monitor-id>/auth \
  -H "Authorization: Bearer $DEVHELM_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "type": "bearer",
      "vaultSecretId": "your-vault-secret-id"
    }
  }'

Monitor auth isn’t settable via CLI create flags — use the YAML auth: block or the monitor auth API (PUT /api/v1/monitors/{monitorId}/auth) on an existing monitor.

Basic auth

secrets:
  - key: ADMIN_BASIC_AUTH
    value: ${ADMIN_BASIC_AUTH}  # Set to "username:password"

monitors:
  - name: Admin Panel
    type: HTTP
    config:
      url: https://admin.example.com/health
      method: GET
    auth:
      type: basic
      secret: ADMIN_BASIC_AUTH
    frequencySeconds: 300
    regions:
      - us-east

API key

secrets:
  - key: VENDOR_API_KEY
    value: ${VENDOR_API_KEY}

monitors:
  - name: Third-Party API
    type: HTTP
    config:
      url: https://api.vendor.com/v1/status
      method: GET
    auth:
      type: api_key
      headerName: x-api-key
      secret: VENDOR_API_KEY
    frequencySeconds: 300
    regions:
      - us-east

Custom header

secrets:
  - key: INTERNAL_TOKEN
    value: ${INTERNAL_TOKEN}

monitors:
  - name: Internal Service
    type: HTTP
    config:
      url: https://internal.example.com/health
      method: GET
    auth:
      type: header
      headerName: X-Internal-Token
      secret: INTERNAL_TOKEN
    frequencySeconds: 60
    regions:
      - us-east

Custom headers (alternative)

For simple cases, you can also pass headers directly in the HTTP config:

monitors:
  - name: API with Custom Header
    type: HTTP
    config:
      url: https://api.example.com/status
      method: GET
      customHeaders:
        X-Custom-Auth: ${CUSTOM_AUTH_TOKEN}
    frequencySeconds: 60
    regions:
      - us-east

The auth configuration is preferred over customHeaders for credentials because vault secrets are encrypted at rest and never logged.

Troubleshooting

Getting 401 Unauthorized

Verify the vault secret value is correct: devhelm secrets list shows secret names but not values. Recreate the secret if in doubt.

Getting 403 Forbidden

The credentials are valid but lack permission. Check that the API key or token has read access to the health endpoint.

Auth works locally but not from probes

Some APIs restrict access by IP. Ensure DevHelm probe IPs are allowlisted. Contact support for the current probe IP ranges.

Next steps

HTTP monitor reference

Full HTTP configuration and auth details.

Monitors guide

Configure all monitor types with code examples.

Monitoring as Code

Manage authenticated monitors in YAML.

Overview

Getting Started

Monitoring Guides

Alerting Guides

Incident Guides

Status Data Guides

Monitoring as Code Guides

Monitoring Authenticated Endpoints

Supported auth types

Store credentials in the vault

Create an authenticated monitor

Bearer token

Basic auth

API key

Custom header

Custom headers (alternative)

Troubleshooting

Next steps

HTTP monitor reference

Monitors guide

Monitoring as Code

​Supported auth types

​Store credentials in the vault

​Create an authenticated monitor

​Bearer token

​Basic auth

​API key

​Custom header

​Custom headers (alternative)

​Troubleshooting

​Next steps

HTTP monitor reference

Monitors guide

Monitoring as Code

Supported auth types

Store credentials in the vault

Create an authenticated monitor

Bearer token

Basic auth

API key

Custom header

Custom headers (alternative)

Troubleshooting

Next steps