API keys, scopes, and the public REST API

Everything you can do in the Valpero dashboard, you can also do via the public REST API. Mint a key, attach scopes, send requests.

API reference (Redoc): https://valpero.com/docs/api

Mint a key

1. Open Dashboard → Settings → API keys.
2. Click New key, give it a name (you'll see this name in the audit log when the key is used).
3. Choose scopes — see below.
4. Save. The full token (val_key_xxxxxxxx…) is shown once — copy it and store securely. We only keep a SHA-256 hash.

You can revoke a key at any time on the same page; it stops working immediately, no propagation delay.

Scopes

Each key can have any subset of these:

The default for a new key is read-only across the board: account:read, monitors:read, incidents:read. Tick the *:write ones only when you need them.

Authenticate

Bearer token, sent in the Authorization header:

curl https://valpero.com/api/v1/monitors \
  -H "Authorization: Bearer val_key_xxxxxxxx"

Useful endpoints

# List monitors
GET /api/v1/monitors

# Create a monitor (needs monitors:write)
POST /api/v1/monitors
{
  "url": "https://example.com",
  "name": "Marketing site",
  "check_type": "http",
  "check_interval": 60,
  "regions": ["hel", "fra", "usc"]
}

# Pause / resume
POST /api/v1/monitors/{id}/pause
POST /api/v1/monitors/{id}/resume

# Trigger an immediate check (out-of-schedule)
POST /api/v1/monitors/{id}/check

# Recent checks for charts
GET /api/v1/monitors/{id}/checks?page=1&limit=200

# List incidents (optionally only ongoing)
GET /api/v1/incidents?status=ongoing

# Acknowledge / resolve
POST /api/v1/incidents/{id}/acknowledge
{ "note": "I'm on it." }

POST /api/v1/incidents/{id}/resolve

The full reference, with request/response shapes, lives in the Redoc viewer at https://valpero.com/docs/api.

Rate limits

Per-key limits depend on your plan:

Every API response carries X-RateLimit-Remaining and Retry-After headers. When you hit the limit you get HTTP 429 — back off and retry.

Webhook signatures

If you've configured a webhook on a monitor, every outbound POST is signed with HMAC-SHA256 using the per-monitor secret. Header:

X-Valpero-Signature: sha256=<hex>

Compute the same HMAC over the raw request body and compare in constant time. Rotate the secret via POST /api/v1/webhooks/rotate-secret.

Bring-your-own-Prometheus

If you'd rather scrape than push: the Prometheus-compatible endpoint is at /api/metrics and uses the same Bearer-token auth. Configure your Prometheus job:

- job_name: valpero
  bearer_token: val_key_…
  metrics_path: /api/metrics
  scheme: https
  static_configs:
    - targets: [valpero.com]

Exports per-monitor up, response_time_ms, uptime_7d, incidents_open, ssl_days_remaining.

Rotation hygiene

• Use one key per integration. Naming them terraform, gh-actions, grafana etc. makes audit logs readable.
• Rotate annually or whenever the integration changes hands.
• Revoke before deleting users / leaving teams.