Authentication overview

Traceable uses a tiered authentication model. Most read operations on public DPP data require no authentication at all. Actions that access restricted data or initiate authority access requests require a bearer token API key.

Public endpoints (no authentication required)

The following endpoints are openly accessible without any credentials:

Endpoint	Description
GET /api/dpp/{slug}	Retrieve published DPP data
GET /api/dpp/{slug}/jsonld	Retrieve DPP in JSON-LD format
GET /api/health	Platform health status

These endpoints 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.

Authenticated endpoints

The following endpoints require a valid API key:

Endpoint	Description
POST /api/poli/access	Submit a PoLI authority access request
GET /api/poli/verify	Check PoLI access request status

API key format

API keys are opaque bearer tokens. Include the key in every authenticated request using the Authorization HTTP header:

Authorization: Bearer trc_live_a8f3k2p9x7m1n4q6r0s5v8w2y4z7b1c3d6e9f2g5h8j1

The key must be included in the header exactly as shown — the Bearer prefix (with a trailing space) is required.

Example authenticated request

curl -X POST https://app.traceable.digital/api/poli/access \
  -H "Authorization: Bearer trc_live_a8f3k2p9x7m1n4q6r0s5v8w2y4z7b1c3d6e9f2g5h8j1" \
  -H "Content-Type: application/json" \
  -d '{
    "productSlug": "swiftvolt-48v-100ah-ev-pack",
    "requestingEntity": "Netherlands Authority for Consumers and Markets (ACM)",
    "legalBasis": "EU Battery Regulation 2023/1542 Article 74 — Market Surveillance",
    "contactEmail": "dpp-access@acm.nl",
    "jurisdiction": "NL"
  }'

A missing or malformed Authorization header returns:

{
  "error": "Authentication required",
  "code": "UNAUTHORIZED"
}

An invalid or revoked key returns:

{
  "error": "Invalid or revoked API key",
  "code": "INVALID_API_KEY"
}

How to obtain an API key

API keys are generated from within the Traceable Company Portal:

1. Log in to app.traceable.digital with your operator account
2. Navigate to Settings → API Keys
3. Click New Key
4. Enter a descriptive name for the key (for example: poli-integration-prod or ci-health-check)
5. Copy the key immediately — it is shown only once at creation time

Generating API keys requires an active Traceable operator account. If your organisation does not have an account, contact support@traceable.digital.

Key scopes

All API keys currently have a single scope:

Scope	Permissions
read	Submit and check PoLI access requests; read any data returned by authenticated endpoints

Additional scopes may be introduced in future API versions. Existing keys will not gain new permissions automatically — you will be notified if scope changes require action.

Multiple keys per account

An account can hold multiple API keys simultaneously. This is useful for:

• Isolating credentials between environments (production vs. staging integrations)
• Providing separate keys to different integration partners
• Enabling zero-downtime key rotation (create new key, update integrations, delete old key)

Keys are independent — revoking one does not affect others. Each key appears with its name, creation date, and last-used timestamp in Settings → API Keys.