> ## 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.

# Monitoring Authenticated Endpoints

> Monitor private APIs and authenticated endpoints with DevHelm vault secrets

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.

<Accordion title="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)
</Accordion>

## 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:

```bash theme={null}
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

<CodeGroup>
  ```yaml devhelm.yml theme={null}
  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
  ```

  ```bash API theme={null}
  # 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"
      }
    }'
  ```
</CodeGroup>

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

```yaml theme={null}
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

```yaml theme={null}
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

```yaml theme={null}
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:

```yaml theme={null}
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
```

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

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Getting 403 Forbidden">
    The credentials are valid but lack permission. Check that the API key or token has read access to the health endpoint.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="HTTP monitor reference" icon="globe" href="/monitoring/http/overview">
    Full HTTP configuration and auth details.
  </Card>

  <Card title="Monitors guide" icon="signal" href="/guides/monitors">
    Configure all monitor types with code examples.
  </Card>

  <Card title="Monitoring as Code" icon="file-code" href="/guides/monitoring-as-code">
    Manage authenticated monitors in YAML.
  </Card>
</CardGroup>