Copy page

Reference

Authentication

Every request to $CXH_BASE_URL/v1/$TENANT/* MUST include an Authorization header with a CollectiveX Health partner API key.

Header format

Code
Authorization: ApiKey zpka_<32+ alphanumeric chars>

ApiKey is the only accepted scheme. Bearer is rejected with 401.

Example:

Code
curl -sS "$CXH_BASE_URL/v1/$TENANT/recommendation" \
  -H "Authorization: ApiKey $CXH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '...'

How keys are issued

• Keys are minted by CollectiveX Health in the Zuplo dashboard. They never transit our source code, Secret Manager, or CI logs.
• You receive the key out-of-band (encrypted channel: 1Password share, PGP, or equivalent). Raw keys are never sent over email or Slack in plaintext.
• Each key is scoped to one partner tenant (cxh-sandbox-TENANT or cxh-prod-TENANT). Sandbox keys never work against prod routes and vice versa.
• The key embeds your tenant identifier internally. You do not send X-Zuplo-Partner-Id yourself — the gateway injects it from the key.

Rotation

Standard rotation cadence is quarterly or on demand.

To request rotation:

1. Contact support with your current tenant identifier and the reason (scheduled rotation / suspected compromise / developer churn).
2. CollectiveX mints a new key and hands it over via the same out-of-band channel used for the original.
3. You have a 24-hour overlap window where both the old and new keys are valid. Deploy the new key to all production callers within that window.
4. The old key is revoked automatically at the end of the 24-hour window. CollectiveX notifies you once revocation is confirmed.

What the gateway validates

Zuplo validates:

1. Key presence — missing or malformed Authorization header → 401. The body is Zuplo's RFC 7807 problem+json envelope (see errors.md for the actual shape).
2. Key validity — key exists in Zuplo's key store and is not revoked → 401 on failure.
3. Key-to-route scope — key is entitled to hit /v1/TENANT/* → 403 on mismatch.
4. Rate limit — key is under 30 req/min → 429 on breach. See rate-limits.md.

After validation, Zuplo injects the X-Zuplo-Partner-Id header and forwards the request to the CollectiveX origin. The origin then validates:

5. Partner consent — active consent record exists for the partner tenant → 403 on revocation. See errors.md for consent_not_provisioned vs consent_revoked.

All five checks happen before your request body is parsed. A valid request body with an invalid key never triggers clinical processing.

Questions?

See support.md.