Watch an endpoint that needs a credential

Job reports are part of Vaicoa Pro and Vaicoa Team.

An uptime check cannot watch an endpoint that needs a token, or one on a private address. Run the request yourself from cron, on a machine that can reach the endpoint, and report the result as a job. Vaicoa then alerts you when the request fails or stops succeeding, and the credential never leaves your machine.

Checks send no credentials, headers or query strings and connect only to public addresses, so that nothing secret ends up in shared briefs or Claude’s answers, and no check can be pointed into a private network. See Uptime checks reference.

What you need: a server that runs the agent and can reach the endpoint. The examples use https://10.0.1.5:8443/health and a bearer token.

Steps

Store the credential in a file that only root can read, for example /etc/cloudviewer-probe/api-health.header with mode 0600:
```
Authorization: Bearer <your-api-token>
```
curl reads headers from a file with -H @file (curl 7.55 or later), so the secret does not appear on the command line, where other users could see it in the process list.
Write a small probe script, /usr/local/bin/api-health, and make it executable (chmod 755):
```
#!/bin/sh
# Exits non-zero when the endpoint fails, and logs why.
out=$(curl -fsS --max-time 10 -o /dev/null \
  -H @/etc/cloudviewer-probe/api-health.header \
  https://10.0.1.5:8443/health 2>&1) || {
  rc=$?
  logger -p user.warning -t api-health "$out"
  exit "$rc"
}
```
-f makes curl fail on an HTTP status of 400 or above, and --max-time on a hang. A job report carries no message, so the script writes curl’s error to journald at warning priority, where it appears in the server’s log context. For a certificate from your own CA, add --cacert.
Run it once by hand as root and check that it succeeds:
Terminal window
```
/usr/local/bin/api-health; echo "exit $?"
```
A job that has never succeeded never goes stale, so the first report should be a success.
Add the cron line to root’s crontab:
```
*/5 * * * * cloudviewer-report --job api-health --max-age 20m -- /usr/local/bin/api-health
```
cloudviewer-report runs the script, sends its exit code and duration, and returns the exit code unchanged. It reads the agent token from /etc/cloudviewer-agent/agent.env, which only root can read. To run the job as another user, give that user a copy of the token and pass --token-file /path/to/token.

What you will see

After the first run, api-health appears in the Jobs section of the server’s detail screen, with its last run and last success. Two alerts come with it:

Job failed when the latest run failed and no successful run has replaced it for five minutes.
Job stale when no run has succeeded for longer than --max-age, for example because cron stopped running it. Set --max-age a few intervals longer than the schedule, so one missed run does not alert.

On a failed job, Why it failed opens the log context, where the line from logger shows curl’s error, such as a timeout or the HTTP status.

The endpoint is on another machine

The job does not have to run on the server it watches. If the endpoint belongs to another monitored server, report with that server’s agent token (--token-file), and the job appears on that server’s screen instead. On a machine without the agent, use the curl call from Get told when a job fails instead of cloudviewer-report. The logger line then stays on that machine.

Limits

A token can send 2 reports a minute, with a burst of 16, so a run every five minutes is well inside. A server can have 16 jobs. Job names use lowercase letters, digits, -, _ and ., up to 64 characters. All fields and error codes: Job reports API.

Next: When something needs attention follows a failed job from the alert to the cause.