Authentication Guide - Prometheus Pushgateway

API Overview

This API provides Prometheus Pushgateway-compatible endpoints for pushing and retrieving metrics. Authentication is optional but recommended for production deployments.

Base URL: https://your-worker.workers.dev

Content Type: Metrics endpoints return text/plain; version=0.0.4 (Prometheus format)

REST API Reference

Push Metrics

PUT/POST /metrics/job/{job}[/{label}/{value}]...

Push or replace metrics for a grouping. Additional labels can be specified as path parameters.

Parameters:

job (path) - Job name
label (path, optional) - Additional grouping label name
value (path, optional) - Additional grouping label value

Body: Prometheus metrics in text format

Examples:

curl -X PUT --data-binary 'cpu_usage 0.85' \
  /metrics/job/my_job/instance/server1

Retrieve Metrics

GET /metrics/job/{job}[/{label}/{value}]...

Retrieve metrics for a specific grouping.

Parameters:

job (path) - Job name
label (path, optional) - Additional grouping label name
value (path, optional) - Additional grouping label value

Response: Metrics in Prometheus text format

curl /metrics/job/my_job/instance/server1

Get All Metrics

GET /metrics

Retrieve all metrics across all jobs and groupings.

Response: All metrics in Prometheus text format

curl /metrics

Delete Metrics

DELETE /metrics/job/{job}[/{label}/{value}]...

Delete metrics for a specific grouping.

Parameters:

job (path) - Job name
label (path, optional) - Additional grouping label name
value (path, optional) - Additional grouping label value

Examples:

# Delete specific instance
curl -X DELETE /metrics/job/my_job/instance/server1

# Delete all instances for a job
curl -X DELETE /metrics/job/my_job

Get Targets

GET /api/v1/targets

Get list of all metric targets (Prometheus service discovery format).

Response: JSON with target information

curl /api/v1/targets

Health Check

GET /health

Get service health status.

Response: JSON health information

curl /health

Web UI

GET /

Access the web interface for browsing and managing metrics.

Response: HTML interface

Documentation

GET /docs

Access this API documentation page.

Response: HTML documentation

Authentication Methods

Three authentication methods are supported, checked in order:

Basic Auth - Username/password via HTTP Basic authentication
JWT/OIDC - Bearer tokens validated against an OIDC provider
API Tokens - Static tokens for service-to-service authentication

Basic Authentication

Configuration

Set these environment variables:

PUSHGATEWAY_AUTH_USER=admin
PUSHGATEWAY_AUTH_PASS=your-secure-password

For production, use Cloudflare Secrets:

npx wrangler secret put PUSHGATEWAY_AUTH_USER
npx wrangler secret put PUSHGATEWAY_AUTH_PASS

Usage Examples

# Using curl -u flag
curl -u admin:your-secure-password \
  -X PUT --data-binary 'uptime_seconds 3600' \
  https://your-worker.workers.dev/metrics/job/my_job

# Using Authorization header
curl -H "Authorization: Basic $(echo -n 'admin:your-secure-password' | base64)" \
  -X PUT --data-binary 'uptime_seconds 3600' \
  https://your-worker.workers.dev/metrics/job/my_job

JWT/OIDC Authentication

Configuration

Set these environment variables:

JWT_ISSUER=https://accounts.google.com
JWT_AUDIENCE=your-oidc-client-id
JWKS_URI=https://accounts.google.com/.well-known/jwks.json

JWKS_URI is optional and defaults to {issuer}/.well-known/jwks.json.

For production, use Cloudflare Secrets:

npx wrangler secret put JWT_ISSUER
npx wrangler secret put JWT_AUDIENCE

Usage Examples

# Using Authorization header
curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6..." \
  -X PUT --data-binary 'uptime_seconds 3600' \
  https://your-worker.workers.dev/metrics/job/my_job

Obtain JWT tokens from your OIDC provider (Google, Auth0, etc.).

API Token Authentication

Configuration

Set this environment variable with comma-separated tokens:

API_TOKENS=token1,token2,token3

For production, use Cloudflare Secrets:

npx wrangler secret put API_TOKENS

Usage Examples

# Using Bearer header
curl -H "Authorization: Bearer token1" \
  -X PUT --data-binary 'uptime_seconds 3600' \
  https://your-worker.workers.dev/metrics/job/my_job

# Using X-API-Key header
curl -H "X-API-Key: token1" \
  -X PUT --data-binary 'uptime_seconds 3600' \
  https://your-worker.workers.dev/metrics/job/my_job

Authentication Flow

When authentication is configured, requests are validated in this order:

Authorization: Bearer <token> → Try JWT validation → If fails, try API tokens → If fails, return 401
Authorization: Basic <creds> → Check username/password → If fails, return 401
X-API-Key: <token> → Check API tokens → If fails, return 401
No auth headers → Return 401

Note: Authentication is bypassed for requests from localhost (development/testing).