Authentication & API Keys

Every Pipelet HTTP API uses API keys sent in the X-API-Key request header. There are no OAuth flows, no JWTs, no per-user auth. One key per integration.

How keys work

• Keys are configured in config.json under headless_cpms.api_keys (or via environment variables — see below).
• Each key has a name (your label), an enabled flag, and the secret itself.
• A request without a valid key gets 401 Unauthorized.
• The /docs/* documentation routes are open — everything else requires a key.

{
  "headless_cpms": {
    "host": "0.0.0.0",
    "port": 8080,
    "api_keys": [
      { "key": "hcpms_live_a4b9...", "name": "Production",  "enabled": true  },
      { "key": "hcpms_live_e7c1...", "name": "Staging",     "enabled": true  },
      { "key": "hcpms_live_old__", "name": "Old (rotate)", "enabled": false }
    ]
  }
}

Sending the key

curl

curl -H "X-API-Key: hcpms_live_a4b9..." \
  http://localhost:8080/api/v1/stations

Python

import requests
r = requests.get(
    "http://localhost:8080/api/v1/stations",
    headers={"X-API-Key": "hcpms_live_a4b9..."},
)

JavaScript

const r = await fetch("http://localhost:8080/api/v1/stations", {
  headers: { "X-API-Key": "hcpms_live_a4b9..." },
});

wallecpms SDK

from wallecpms import HeadlessCPMS
cpms = HeadlessCPMS("http://localhost:8080", api_key="hcpms_live_a4b9...")

Generating a key

Use any cryptographically secure random generator. The hcpms_live_ prefix is a convention, not a requirement — it makes leaked keys easy to grep for:

echo "hcpms_live_$(openssl rand -hex 24)"

Add the resulting string to api_keys and reload the gateway:

docker compose restart cpms-headless

Rotation

Pipelet supports multiple active keys at once, so rotation is a four-step zero-downtime process:

1. Generate the new key and add it to api_keys with enabled: true.
2. Reload the gateway. Now both old and new keys work.
3. Roll the new key out to every consumer (CI, frontends, partners).
4. Set the old key’s enabled: false. Reload one more time.

Don’t delete the old key — leaving it in place with enabled: false makes the audit trail clearer.

Webhook secrets

API keys protect inbound requests to the gateway. Webhooks (outbound from Pipelet to your endpoint) are authenticated separately, with a per-webhook secret. See Webhooks → Overview & Signing.

Storage best practices

• Never commit a key to git. Use a secret manager (HashiCorp Vault, AWS Secrets Manager, Doppler, 1Password CLI…).
• Inject via env var rather than baking into Docker images.
• Rotate keys at least quarterly, immediately after personnel changes.
• Use one key per consumer so you can revoke without collateral damage.

Never log API keys

The Pipelet gateway will redact X-API-Key from its access logs by default — check that your reverse proxy and CDN do the same. Cloudflare, nginx and Caddy all leak headers in their default access log format.

Multi-tenancy

For multi-tenant deployments where each customer gets their own key namespace, see Self-Hosting → Production Hardening (coming in Phase 2). The short version: run one gateway per tenant, or sit a small auth-proxy in front that maps tenant subdomains to upstream keys.