Skip to main content

Authentication overview

Traceable's HTTP surfaces use different authentication models depending on what they do. Public DPP reads need no credentials. Programmatic authoring uses bearer API keys with request signing. Authority access to restricted fields is a human web flow, not a keyed API. BMS telemetry ingestion uses HMAC request signing.

Public endpoints (no authentication required)​

The following endpoints are openly accessible without any credentials:

EndpointDescription
GET /api/dpp/{slug}Retrieve published (public) DPP data
GET /api/dpp/{slug}/jsonldRetrieve the DPP in JSON-LD format
GET /api/healthPlatform health status

These are intentionally unauthenticated because Digital Product Passports under EU Battery Regulation 2023/1542 must be publicly accessible to any person or system presenting a QR code or knowing a product's identifier. They return public fields only — restricted fields are never served by the JSON API.

Programmatic authoring — Integration API (bearer keys)​

The one bearer-key API surface is the Integration API (/api/v1), GA on production as of v0.99.6.1. It authors DPPs from an ERP or PLM using pk_live_* keys with HMAC request signing on writes and per-request idempotency keys. It also supports:

  • Sandbox mode — pk_test_* keys (with X-Traceable-Mode: test) that write throwaway data, separate from live.
  • Per-key IP allow-lists (allowedCidrs, fail-closed) and programmatic key management/rotation.
  • Privileged scopes keys:admin and gdpr:admin, minted only from the Company Portal, never via the normal scope picker.

Full reference: Integration API: Authentication. There is no separate general-purpose public API key beyond the Integration API.

Authority access — PoLI (no API key)​

Access to restricted DPP fields for a Person of Legal Interest (a market surveillance authority, customs body, and so on) is not a keyed API. It is a human-reviewed web flow: an authority requests access from the public DPP page, confirms their email, the manufacturer approves, and the authority is then granted access in their browser. There is no bearer token and no JSON endpoint that returns restricted fields.

See PoLI access for the full flow.

BMS telemetry ingestion (HMAC signing)​

The BMS telemetry ingestion endpoint uses HMAC-SHA256 request signing with a shared secret rather than a bearer token. It is specific to the BMS surface.

Key points:

  • The shared secret is provisioned under Settings → API Keys → BMS Secrets, separate from Integration API keys.
  • Each request includes X-Traceable-BMS-Secret (the plaintext secret) and X-Traceable-Signature (an HMAC-SHA256 signature over the request body).
  • A 5-minute replay-protection window is enforced.
  • The server stores only a SHA-256 hash of the secret; the plaintext is never persisted after provisioning.

See BMS Endpoints for full signing instructions and code examples.