Skip to main content

API keys

Traceable's bearer-key API is the Integration API (/api/v1), used to author Digital Product Passports programmatically. Its keys use the pk_live_ prefix and are paired with a signing secret for HMAC request signing.

This page is a pointer. The full, authoritative key documentation lives with the Integration API:

Quick facts​

  • Keys are minted in the operator portal under Settings → API Keys. The key (pk_live_…) and its signing secret are each shown once at creation; store them in a secret manager immediately.
  • A key identifies your company (tenant) and carries the scopes you assign. You never send a companyId.
  • Sandbox vs live mode. Keys are either live (pk_live_*) or sandbox (pk_test_*). A sandbox request must send X-Traceable-Mode: test (else 400), and its data never touches a real passport. See Sandbox mode.
  • Per-key IP allow-list. A key can restrict itself to a set of CIDR ranges (allowedCidrs), enforced fail-closed. See Per-key IP allow-list.
  • Rotation. Rotate without downtime (create, deploy, verify, revoke), or programmatically via /api/v1/keys. Keys older than 90 days trigger a Warning: 299 header. See Programmatic key management.
  • Privileged scopes. keys:admin (key management) and gdpr:admin (GDPR endpoints) are minted only from the Company Portal, never via the normal scope picker. See Privileged scopes.
  • Rate limits apply per key. See Rate Limiting.

What does not use an API key​

  • Public DPP reads (GET /api/dpp/{slug}, /jsonld, /api/health) need no credentials.
  • PoLI authority access is a human web flow with no key — see PoLI access.
  • BMS telemetry ingestion uses HMAC signing with a shared secret, not a bearer key — see BMS Endpoints.